Module: GetText

Module | GetText
In: | lib/gettext/poparser.rb lib/gettext/textdomain.rb lib/gettext/utils.rb lib/gettext/rails.rb lib/gettext/version.rb lib/gettext/rgettext.rb lib/gettext/rmsgfmt.rb lib/gettext/container.rb lib/gettext/textdomainmanager.rb lib/gettext/cgi.rb lib/gettext/rmsgmerge.rb lib/gettext/parser/glade.rb lib/gettext/parser/ruby.rb lib/gettext/parser/active_record.rb lib/gettext/parser/erb.rb lib/gettext/erb.rb lib/gettext.rb

### Methods

N_ Nn_ _ add_default_locale_path bindtextdomain bindtextdomain_to cached= cached? cgi cgi= clear_cache create_mofiles current_textdomain_info gettext locale locale= msgmerge n_ ngettext np_ npgettext ns_ nsgettext output_charset output_charset= p_ pgettext remove_all_textdomains rgettext rmsgfmt rmsgmerge s_ set_cgi set_locale set_locale_all set_output_charset setlocale sgettext textdomain textdomain_to update_pofiles

### Included Modules

GetText GetText

### Classes and Modules

Module GetText::ActiveRecordParser
Module GetText::Container
Module GetText::ErbContainer
Module GetText::ErbParser
Module GetText::GladeParser
Module GetText::Rails
Module GetText::RubyParser
Class GetText::NoboundTextDomainError
Class GetText::PoParser
Class GetText::TextDomain
Class GetText::TextDomainManager

### Constants

BOM_UTF8 | = | [0xef, 0xbb, 0xbf].pack("c3")
VERSION | = | "1.93.0"

### Public Instance methods

N_(msgid)

This function does nothing. But it is required in order to recognize the msgid by rgettext.

- msgid: the message id.
- Returns: msgid.

Nn_(msgid, msgid_plural)

This is same function as N_ but for ngettext.

- msgid: the message id.
- msgid_plural: the plural message id.
- Returns: msgid.

_(msgid)

Alias for gettext

add_default_locale_path(path)

Add default locale path.

- path: a new locale path. (e.g.) "/usr/share/locale/%{locale}/LC_MESSAGES/%{name}.mo" (‘locale’ => "ja_JP", ‘name’ => "textdomain")
- Returns: the new DEFAULT_LOCALE_PATHS

bindtextdomain(domainname, options = {})

Bind a textdomain(%{path}/%{locale}/LC_MESSAGES/%{domainname}.mo) to your program. Normally, the texdomain scope becomes a ruby-script-file. So you need to call this function each ruby-script-files. On the other hand, if you call this function under GetText::Container (gettext/container, gettext/erb, gettext/rails), the textdomain scope becomes a Class/Module.

- domainname: the textdomain name.
- options: options as an Hash.
  - :path - the path to the mo-files. When the value is nil, it will search default paths such as /usr/share/locale, /usr/local/share/locale)
  - :locale - the locale string such as "ja_JP.UTF-8". Generally, you should use GetText.set_locale instead. The value is searched order by: the value of this value > System default language.
  - :charset - output charset. This affect the current textdomain only. Generally, you should use GetText.set_output_charset instead. The value is searched order by: the value of Locale.set_output_charset > ENV["OUTPUT_CHARSET"] > this value > System default charset.
- Returns: the GetText::TextDomainManager.

Note: Don‘t use locale_, charset argument(not in options). They are remained for backward compatibility.

bindtextdomain_to(klass, domainname, options = {})

Includes GetText module and bind a textdomain to a class.

- klass: the target ruby class.
- domainname: the textdomain name.
- options: options as an Hash. See GetText.bindtextdomain.

cached=(val)

Set the value whether cache messages or not. true to cache messages, otherwise false.

Default is true. If $DEBUG is false, messages are not checked even if this value is true.

cached?()

Return the cached value.

cgi()

Gets the CGI object. If it is nil, returns new CGI object.

- Returns: the CGI object

cgi=(cgi_)

Same as GetText.set_cgi.

- cgi_: CGI object
- Returns: cgi_

clear_cache()

Clear the cached messages.

create_mofiles(verbose = false, podir = "./po", targetdir = "./data/locale", targetpath_rule = "%s/LC_MESSAGES")

Creates mo-files using #{po_root}/#{lang}/*.po an put them to #{targetdir}/#{targetpath_rule}/.

This is a convenience function of GetText.rmsgfmt for plural target files.

- verbose: true if verbose mode, otherwise false
- po_root: the root directory of po-files.
- targetdir: the target root directory where the mo-files are stored.
- targetpath_rule: the target directory for each mo-files. "%s" becomes "#{lang}" under po_root.

current_textdomain_info(options = {})

Show the current textdomain information. This function is for debugging.

- options: options as a Hash.
  - :with_messages - show informations with messages of the current mo file. Default is false.
  - :out - An output target. Default is STDOUT.
  - :with_paths - show the load paths for mo-files.

gettext(msgid)
_(msgid)

Translates msgid and return the message. This doesn‘t make a copy of the message.

You need to use String#dup if you want to modify the return value with destructive functions.

(e.g.1) _("Hello ").dup << "world"

But e.g.1 should be rewrite to:

(e.g.2) _("Hello %{val}") % {:val => "world"}

Because the translator may want to change the position of "world".

- msgid: the message id.
- Returns: localized text by msgid. If there are not binded mo-file, it will return msgid.

locale()

Gets the current locale.

- Returns: a current Locale::Object

locale=(locale)

Sets the default/current locale. This method haves the strongest infulence. All of the Textdomains are set the new locale.

Note that you shouldn‘t use this for your own Libraries.

- locale: a locale string or Locale::Object
- Returns: a locale string

msgmerge(defpo, refpo, app_version)

Merges two Uniforum style .po files together.

Note This function requires "msgmerge" tool included in GNU GetText. So you need to install GNU GetText.

The def.po file is an existing PO file with translations which will be taken over to the newly created file as long as they still match; comments will be preserved, but extracted comments and file positions will be discarded.

The ref.pot file is the last created PO file with up-to-date source references but old translations, or a PO Template file (generally created by rgettext); any translations or comments in the file will be discarded, however dot comments and file positions will be preserved. Where an exact match cannot be found, fuzzy matching is used to produce better results.

Usually you don‘t need to call this function directly. Use GetText.update_pofiles instead.

- defpo: a po-file. translations referring to old sources
- refpo: a po-file. references to new sources
- app_version: the application information which appears "Project-Id-Version: #{app_version}" in the pot/po-files.
- Returns: self

n_(arg1, arg2, arg3 = nil)

Alias for ngettext

ngettext(msgid, msgid_plural, n)
ngettext(msgids, n) # msgids = [msgid, msgid_plural]
n_(msgid, msgid_plural, n)
n_(msgids, n) # msgids = [msgid, msgid_plural]

The ngettext is similar to the gettext function as it finds the message catalogs in the same way. But it takes two extra arguments for plural form.

- msgid: the singular form.
- msgid_plural: the plural form.
- n: a number used to determine the plural form.
- Returns: the localized text which key is msgid_plural if n is plural(follow plural-rule) or msgid. "plural-rule" is defined in po-file.

np_(msgctxt, arg1, arg2 = nil, arg3 = nil)

Alias for npgettext

npgettext(msgctxt, msgid, msgid_plural, n)
npgettext(msgctxt, msgids, n) # msgids = [msgid, msgid_plural]
np_(msgctxt, msgid, msgid_plural, n)
np_(msgctxt, msgids, n) # msgids = [msgid, msgid_plural]

The npgettext is similar to the nsgettext function.

      e.g.) np_("Special", "An apple", "%{num} Apples", num) == ns_("Special|An apple", "%{num} Apples", num)

- msgctxt: the message context.
- msgid: the singular form.
- msgid_plural: the plural form.
- n: a number used to determine the plural form.
- Returns: the localized text which key is msgid_plural if n is plural(follow plural-rule) or msgid. "plural-rule" is defined in po-file.

ns_(arg1, arg2, arg3 = "|", arg4 = "|")

Alias for nsgettext

nsgettext(msgid, msgid_plural, n, div = "|")
nsgettext(msgids, n, div = "|") # msgids = [msgid, msgid_plural]
n_(msgid, msgid_plural, n, div = "|")
n_(msgids, n, div = "|") # msgids = [msgid, msgid_plural]

The nsgettext is similar to the ngettext. But if there are no localized text, it returns a last part of msgid separeted "div".

- msgid: the singular form with "div". (e.g. "Special|An apple")
- msgid_plural: the plural form. (e.g. "%{num} Apples")
- n: a number used to determine the plural form.
- Returns: the localized text which key is msgid_plural if n is plural(follow plural-rule) or msgid. "plural-rule" is defined in po-file.

output_charset()

Gets the current output_charset which is set using GetText.set_output_charset.

- Returns: output_charset.

output_charset=(charset)

Same as GetText.set_output_charset

- charset: an output_charset
- Returns: charset

p_(msgctxt, msgid)

Alias for pgettext

pgettext(msgctxt, msgid)
p_(msgctxt, msgid)

Translates msgid with msgctxt. This methods is similer with s_().

     e.g.) p_("File", "New")   == s_("File|New")
           p_("File", "Open")  == s_("File|Open")

- msgctxt: the message context.
- msgid: the message id.
- Returns: the localized text by msgid. If there are no localized text, it returns msgid.

See: www.gnu.org/software/autoconf/manual/gettext/Contexts.html

remove_all_textdomains()

for testing.

rgettext(targetfiles = nil, out = STDOUT)

Creates a po-file from targetfiles(ruby-script-files, ActiveRecord, .rhtml files, glade-2 XML files), then output the result to out. If no parameter is set, it behaves same as command line tools(rgettet).

This function is a part of GetText.create_pofiles. Usually you don‘t need to call this function directly.

Note for ActiveRecord, you need to run your database server and configure the config/database.xml correctly before execute this function.

- targetfiles: An Array of po-files or nil.
- out: output IO or output path.
- Returns: self

rmsgfmt(targetfile = nil, output_path = nil)

Creates a mo-file from a targetfile(po-file), then output the result to out. If no parameter is set, it behaves same as command line tools(rmsgfmt).

- targetfile: An Array of po-files or nil.
- output_path: output path.
- Returns: the MOFile object.

rmsgmerge(reference = nil, definition = nil, out = STDOUT)

Experimental

s_(msgid, div = '|')

Alias for sgettext

set_cgi(cgi_)

Sets a CGI object.

- cgi_: CGI object
- Returns: self

set_locale(locale, this_target_only = false)

Sets the current locale to the current class/module

Notice that you shouldn‘t use this for your own Libraries.

- locale: a locale string or Locale::Object.
- this_target_only: true if you want to change the current class/module only.

Otherwise, this changes the locale of the current class/module and its ancestors. Default is false.

- Returns: self

set_locale_all(locale)

Sets current locale to the all textdomains.

Note that you shouldn‘t use this for your own Libraries.

- locale: a locale string or Locale::Object, otherwise nil to use default locale.
- Returns: self

set_output_charset(charset)

Sets charset(String) such as "euc-jp", "sjis", "CP932", "utf-8", … You shouldn‘t use this in your own Libraries.

- charset: an output_charset
- Returns: charset

setlocale(locale)

Alias for locale=

sgettext(msgid, div = '|')
s_(msgid, div = '|')

Translates msgid, but if there are no localized text, it returns a last part of msgid separeted "div".

- msgid: the message id.
- div: separator or nil.
- Returns: the localized text by msgid. If there are no localized text, it returns a last part of msgid separeted "div".

See: www.gnu.org/software/gettext/manual/html_mono/gettext.html#SEC151

textdomain(domainname)

Binds a existed textdomain to your program. This is the same function with GetText.bindtextdomain but simpler(and faster) than bindtextdomain. Notice that you need to call GetText.bindtextdomain first. If the domainname hasn‘t bound yet, raises GetText::NoboundTextDomainError.

- domainname: a textdomain name.
- Returns: the GetText::TextDomainManager.

textdomain_to(klass, domainname)

Includes GetText module and bind an exsited textdomain to a class. See textdomain for more detail.

- klass: the target ruby class.
- domainname: the textdomain name.

update_pofiles(textdomain, files, app_version, po_root = "po", refpot = "tmp.pot")

At first, this creates the #{po_root}/#{domainname}.pot file using GetText.rgettext. Since 2nd time, this updates(merges) the #{po_root}/#{domainname}.pot and all of the #{po_root}/#{lang}/#{domainname}.po files under "po_root" using "msgmerge".

Note "msgmerge" tool is included in GNU GetText. So you need to install GNU GetText.

See <HOWTO maintain po/mo files(www.yotabanana.com/hiki/ruby-gettext-howto-manage.html)> for more detals.

- domainname: the textdomain name.
- targetfiles: An Array of target files or nil (See GetText.rgettext for more details).
- app_version: the application information which appears "Project-Id-Version: #{app_version}" in the pot/po-files.
- po_root: the root directory of po-files.
- refpot: set the temporary file name. You shouldn‘t use this(It will be removed).

     (e.g.) GetText.update_pofiles("myapp", Dir.glob("lib/*.rb"), "myapp 1.0.0")

[Validate]