Ruby-GetText-Package API Reference

ruby-gettext-api

module GetText

Supports to translate the original message to your language properly.

GetText.bindtextdomain(domainname, opts = {})
Bind a textdomain(#{path}/#{locale}/LC_MESSAGES/#{domainname}.mo) to your program. Normally, the texdomain scope becomes a module/class. You can bind textdomains to a module/class.
  • domainname: the textdomain name.
  • opts: options as a Hash.
    • :path - the path to the mofiles. When the value is nil, it will search default paths such as /usr/share/locale, /usr/local/share/locale)
    • :locale - the locale value such as "ja_JP.UTF-8".
    • :charset - output charset. This affect the current textdomain only.
    • :cgi - A CGI object. require "gettext/rails" only. Usually, it should be "request.cgi" in controller classes of Ruby on Rails.

Using locale option

Default
When the value is nil, it is searched in ENV(LC_ALL > LC_CTYPE > LC_MESSAGES > LANG > System Default Language). You shouldn't use this for your own Libraries.
require 'gettext/cgi'
When the value is nil, the locale is set order by "the parameter of bindtextdomain" > "lang" value of QUERY_STRING > "lang" value of Cookie > HTTP_ACCEPT_LANGUAGE value > "en" (English). And the charset is set order by "the argument of bindtextdomain" > HTTP_ACCEPT_CHARSET > "UTF-8".
require 'gettext/rails'
When the value is nil, the locale is set order by "the parameter of bindtextdomain" > params["lang"] > "lang" value of QUERY_STRING > "lang" value of Cookie > HTTP_ACCEPT_LANGUAGE value > "en" (English).

Using charset option

Default
When the value is nil, it is searched in ENV(OUTPUT_CHARSET). If ENV is not set, return a charset by system APIs(used GetACP() on Win32, used nl_langinfo on POSIX). You shouldn't use this for your own Libraries.
require 'gettext/cgi'
When the value is nil, the charset is set order by "the argument of bindtextdomain" > HTTP_ACCEPT_CHARSET > "UTF-8".
GetText.textdomain(domainname)
Bind a existed textdomain to your program. This is the same function with GetText.bindtextdomain but you need to call GetText.bindtextdomain for the same textdomain first.
  • domainname: a textdomain name.
GetText._(msgid)
GetText.gettext(msgid)
Translates msgid and return the message.
  • msgid: the message id.
  • Returns: localized text by msgid. If there are not binded mo-file, it will return msgid.
GetText.n_(msgid, msgid_plural, n)
GetText.n_([msgid, msgid_plural], n)
GetText.ngettext(msgid, msgid_plural, n)
GetText.ngettext([msgid, msgid_plural], n)
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.
GetText.N_(msgid)
This method does nothing. But it is required in order to recognize the msgid by rgettext.
  • msgid: the message id.
  • Returns: msgid.
GetText.s_(msgid, div = "|")
GetText.sgettext(msgid, div = "|")
If there are no localized text, it returns a last part of msgid separeted "div".
GetText.locale=(locale)
Sets locale(String) such as "C", "de", "fr", "it", "ko", "ja_JP.eucJP", "zh_CN.EUC" ... You shouldn't use this for your own Libraries.
  • locale: a locale
  • Returns: locale
GetText.charset=(charset)
Sets charset(String) such as "euc-jp", "sjis", "CP932", "utf-8", ... This affect he current textdomain only. Usually you should use GetText.output_charset= instead. You shouldn't use this for your own Libraries.
  • charset: an charset
  • Returns: charset
GetText.output_charset=(charset)
GetText.set_output_charset(charset)
Sets charset(String) such as "euc-jp", "sjis", "CP932", "utf-8", ... This affect all of the TextDomains which are created after calling this method. You shouldn't use this for your own Libraries.
  • charset: an output_charset
  • Returns: charset
GetText.cgi=(cgi)
GetText.set_cgi(cgi)
"require 'gettext/cgi'". Sets CGI object, otherwise it is created when Locale/GetText methods are called.
  • cgi: An CGI object.
GetText.cgi
Gets the CGI object. When require 'gettext/cgi', this function is added.
  • Returns: the CGI object. if there is no CGI object, create new one and returns it.

Functions for maintainance

GetText.rgettext(targetfiles = nil, out = STDOUT)
When require 'gettext/utils' or 'gettext/rgettext', this function is added. 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). 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: nil
GetText.rmsgfmt(targetfile = nil, output_path = nil)
When require 'gettext/utils' or 'gettext/rmsgfmt', this function is added. 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(rgettet).
  • targetfile: An Array of po-files or nil.
  • output_path: output path.
  • Returns: the MOFile instance.
GetText.create_mofiles(verbose = false, po_root = "./po", targetdir = "./data/locale", targetpath_rule = "%s/LC_MESSAGES")
When require 'gettext/utils' or 'gettext/rmsgfmt', this function is added. Creates mo-files using #{po_root}/#{lang}/*.po an put them to #{targetdir}/#{targetpath_rule}/. This is convenience function of GetText.rmsgfmt. See HOWTO maintain po/mo files for more details.
  • 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.
GetText.update_pofiles(domainname, targetfiles, app_version, po_root = "po", refpot = "tmp.pot")
When require 'gettext/utils', this function is added. 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 included in GNU GetText. So you need to install GNU GetText first. See HOWTO maintain po/mo files for more details.
  • 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).
GetText::ActiveRecordParser.init(config)
"require 'gettext/utils'". Set some preferences to parse ActiveRecord files.
  • config: a Hash of the config. It can takes some values below:
    • :use_classname: If true, the msgids of ActiveRecord become "ClassName|FieldName" (e.g. "Article|Title"). Otherwise the ClassName is not used (e.g. "Title"). Default is true.
    • :db_yml: the path of database.yml. Default is "config/database.yml".
    • :db_mode: the mode of the database. Default is "development"
    • :activerecord_classes: an Array of the superclass of the models. The classes should be String value. Default is ["ActiveRecord::Base"]
      • "ClassName|FieldName" uses GetText.sgettext. So you don't need to translate the left-side of "|". See Documents for Translators for more details.
GetText::ErbParser.init(config)
"require 'gettext/utils'". Set some preferences to parse ERB files.
  • config: a Hash of the config. It can takes some values below:
    • :extnames: An Array of target files extension. Default is [".rhtml"].

module GetText::Container

Deprecated. You shouldn't use this.

module GetText::ErbContainer

require 'gettext/erb'. This module provides basic functions to evaluate plural ERB files(.rhtml) in a TextDomain. You need to implement a class which includes GetText::ErbContainer.

See simple examples below:

require 'gettext/erb'

class SimpleContainer
  include GetText::ErbContainer

  def initialize(domainname, domainpath = nil, locale = nil, charset = nil)
    bindtextdomain(domainname, domainpath, locale)
  end
end

container = SimpleContainer.new("helloerb1", "locale")
puts container.eval_file("/your/erb/file.rhtml")

This module is an example for template engines such as ERB. So you can implement another implementation easily to read gettext/erb.rb.

GetText::ErbContainer.eval_src(rhtml)
Evaluates ERB source(String) in the instance and returns the result HTML.
  • rhtml: an ERB source
  • Returns: the Evaluated ERB result
GetText::ErbContainer.eval_file(rhtmlpath)
Evaluates ERB file in the instance and returns the result HTML.
  • rhtml: an ERB file
  • Returns: the Evaluated ERB result

class String

require 'gettext' extends String#% method which accept "named argument". The translator can know the meaning of the msgids using "named argument" instead of %s/%d style.

%(arg)

Format�Uses str as a format specification, and returns the result of applying it to arg. If the format specification contains more than one substitution, then arg must be an Array containing the values to be substituted. See Kernel::sprintf for details of the format string. This is the default behavior of the String class.

  • arg: an Array or other class except Hash.

(e.g.) "%s, %s" % ["Masao", "Mutoh"]

%(hash)

Same as String%(arg) but it uses hash table. This is recommanded for translators.

  • hash: {:key1 => value1, :key2 => value2, ... }

(e.g.) "%{firstname}, %{familyname}" % {:firstname => "Masao", :familyname => "Mutoh"}

Last modified:2005/12/27 00:56:59
Keyword(s):
References:[Ruby-GetText for Ruby on Rails] [Ruby-GetText-Package document for Developers]