Module: GetText

Module | GetText
In: | lib/gettext/tools.rb lib/gettext/poparser.rb lib/gettext/textdomain.rb lib/gettext/textdomain_manager.rb lib/gettext/textdomain_group.rb lib/gettext/utils.rb lib/gettext/version.rb lib/gettext/mofile.rb lib/gettext/tools/rgettext.rb lib/gettext/tools/rmsgfmt.rb lib/gettext/tools/rmsgmerge.rb lib/gettext/class_info.rb lib/gettext/cgi.rb lib/gettext/locale_path.rb lib/gettext/parser/glade.rb lib/gettext/parser/ruby.rb lib/gettext/parser/erb.rb lib/gettext.rb

### Methods

N_ Nn_ _ bindtextdomain bindtextdomain_to cgi cgi= create_mofiles create_mofiles_org current_locale= gettext locale locale= msgmerge n_ ngettext np_ npgettext ns_ nsgettext output_charset output_charset= p_ pgettext rgettext rmsgfmt rmsgmerge s_ set_cgi set_current_locale set_locale set_locale_all set_output_charset setlocale sgettext update_pofiles update_pofiles_org

### Classes and Modules

Module GetText::ClassInfo
Module GetText::ErbParser
Module GetText::GladeParser
Module GetText::RubyParser
Module GetText::TextDomainManager
Class GetText::LocalePath
Class GetText::MOFile
Class GetText::NoboundTextDomainError
Class GetText::PoParser
Class GetText::TextDomain
Class GetText::TextDomainGroup

### Constants

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

### Public Instance methods

N_(msgid)

makes dynamic translation messages readable for the gettext parser. `_(fruit)` cannot be understood by the gettext parser. To help the parser find all your translations, you can add `fruit = N_("Apple")` which does not translate, but tells the parser: "Apple" needs translation.

- 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

bindtextdomain(domainname, *options)

bindtextdomain(domainname, options = {})

Bind a textdomain(%{path}/%{locale}/LC_MESSAGES/%{domainname}.mo) to your program. Normally, the texdomain scope becomes the class/module(and parent classes/included modules).

- 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)
  - :output_charset - The output charset. Same with GetText.set_output_charset. Usually, L10n library doesn‘t use this option. Application may use this once.
- Returns: the GetText::TextDomainManager.

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.

cgi()

Gets the CGI object. If it is nil, returns new CGI object. This methods is appeared when requiring "gettext/cgi".

- Returns: the CGI object

cgi=(cgi_)

Same as GetText.set_cgi. This methods is appeared when requiring "gettext/cgi".

- cgi_: CGI object
- Returns: cgi_

create_mofiles(options = {})

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

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

- options: options as a Hash.
  - verbose: true if verbose mode, otherwise false
  - po_root: the root directory of po-files.
  - mo_root: the target root directory where the mo-files are stored.
  - mo_path_rule: the target directory for each mo-files.

create_mofiles_org(options = {})

Alias for create_mofiles

current_locale=(lang)

Alias for set_current_locale

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()
locale=(lang)

Alias for set_locale

msgmerge(defpo, refpo, app_version, options={})

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_(msgid, msgid_plural, n = 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, msgids, 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_(msgid, msgid_plural, n="|", seperator = "|")

Alias for nsgettext

nsgettext(msgid, msgid_plural, n, div = "|")
nsgettext(msgids, n, div = "|") # msgids = [msgid, msgid_plural]
ns_(msgid, msgid_plural, n, div = "|")
ns_(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)

Alias for set_output_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

rgettext(targetfiles = nil, out = STDOUT)

Creates a po-file from targetfiles(ruby-script-files, .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.

- 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, seperator = "|")

Alias for sgettext

set_cgi(cgi_)

Sets a CGI object. This methods is appeared when requiring "gettext/cgi".

- cgi_: CGI object
- Returns: self

set_current_locale(lang)

Set the locale to the current thread. Note that if set_locale is set, this value is ignored. If you need, set_locale(nil); set_current_locale(lang)

set_locale(lang)

Set the locale. This value forces the locale whole the programs. This method calls Locale.set_app_language_tags, Locale.default, Locale.current. Use Locale methods if you need to handle locales more flexible.

set_locale_all(lang)

Alias for set_locale

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: self

setlocale(lang)

Alias for set_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.
- separator: separator or nil for no seperation.
- Returns: the localized text by msgid. If there are no localized text, it returns a last part of the msgid separeted by "seperator". `Movie|Location -> Location`

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

update_pofiles(textdomain, files, app_version, options = {})

At first, this creates the #{po_root}/#{domainname}.pot file using GetText.rgettext. In the second step, 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, that should be parsed for messages (See GetText.rgettext for more details).
- app_version: the application information which appears "Project-Id-Version: #{app_version}" in the pot/po-files.
- options: a hash with following possible settings

        :lang    - update files only for one language - the language specified by this option
        :po_root - the root directory of po-files
        :msgmerge - an array with the options, passed through to the gnu msgmerge tool
                    symbols are automatically translated to options with dashes,
                    example: [:no_wrap, :no_fuzzy_matching, :sort_output] translated to '--no-fuzzy-matching --sort-output'
        :verbose - true to show verbose messages. default is false.

Example: GetText.update_pofiles("myapp", Dir.glob("lib/*.rb"), "myapp 1.0.0", :verbose => true)

update_pofiles_org(textdomain, files, app_version, options = {})

Alias for update_pofiles

[Validate]