GetText

Constants

BOM_UTF8
VERSION

Public Instance Methods

N_(msgid) click to toggle source

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.

     # File lib/gettext.rb, line 244
244:   def N_(msgid)
245:     msgid
246:   end
Nn_(msgid, msgid_plural) click to toggle source

This is same function as N_ but for ngettext.

  • msgid: the message id.

  • msgid_plural: the plural message id.

  • Returns: msgid.

     # File lib/gettext.rb, line 252
252:   def Nn_(msgid, msgid_plural)
253:     [msgid, msgid_plural]
254:   end
_(msgid) click to toggle source
Alias for: gettext
bindtextdomain(domainname, *options) click to toggle source

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)

  • Returns: the GetText::TextDomainManager.

    # File lib/gettext.rb, line 63
63:   def bindtextdomain(domainname, *options)
64:     bindtextdomain_to(self, domainname, *options)
65:   end
bindtextdomain_to(klass, domainname, *options) click to toggle source

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.

    # File lib/gettext.rb, line 71
71:   def bindtextdomain_to(klass, domainname, *options) 
72:     if options[0].kind_of? Hash
73:       opts = options[0]
74:     else
75:       # for backward compatibility.
76:       opts = {}
77:       opts[:path] = options[0] if options[0]
78:       opts[:output_charset] = options[2] if options[2]
79:     end
80:     unless (klass.kind_of? GetText or klass.include? GetText)
81:       klass.__send__(:include, GetText)
82:     end
83:     TextDomainManager.bind_to(klass, domainname, opts)
84:   end
cgi() click to toggle source

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

  • Returns: the CGI object

    # File lib/gettext/cgi.rb, line 34
34:   def cgi
35:     Locale.cgi
36:   end
cgi=(cgi_) click to toggle source

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

  • cgi_: CGI object

  • Returns: cgi_

    # File lib/gettext/cgi.rb, line 27
27:   def cgi=(cgi_)
28:     set_cgi(cgi_)
29:     cgi_
30:   end
create_mofiles(options = {}) click to toggle source

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.

    # File lib/gettext/tools.rb, line 89
89:   def create_mofiles(options = {})
90:     options = {:po_root => "./po"}.merge(options)
91: 
92:     Dir.glob(File.join(options[:po_root], "*/*.po")) do |po_file|
93:       mo_file = mo_file_from_po_file(po_file,options)
94:       $stderr.print %[#{po_file} -> #{mo_file} ... ] if options[:verbose]
95:       FileUtils.mkdir_p(File.dirname(mo_file))
96:       rmsgfmt(po_file, mo_file)
97:       $stderr.puts "Done." if options[:verbose]
98:     end
99:   end
Also aliased as: create_mofiles_org
create_mofiles_org(options = {}) click to toggle source
Alias for: create_mofiles
current_locale=(lang) click to toggle source
Alias for: set_current_locale
gettext(msgid) _(msgid) click to toggle source

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.

     # File lib/gettext.rb, line 127
127:   def gettext(msgid)
128:     TextDomainManager.translate_singluar_message(self, msgid)
129:   end
Also aliased as: _
locale() click to toggle source
     # File lib/gettext.rb, line 287
287:   def locale
288:     Locale.current[0]
289:   end
locale=(lang) click to toggle source
Alias for: set_locale
msgmerge(defpo, refpo, app_version, options={}) click to toggle source

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

    # File lib/gettext/tools.rb, line 57
57:   def msgmerge(defpo, refpo, app_version, options={})
58:     verbose = options.delete(:verbose)
59:     puts "msgmerge called" if verbose
60:     $stderr.print defpo + " "
61: 
62:     content = merge_po_files(defpo,refpo,options.delete(:msgmerge),verbose)
63:     
64:     if content.empty?
65:       # report failure
66:       failed_filename = refpo + "~"
67:       FileUtils.cp(refpo, failed_filename)
68:       $stderr.puts _("Failed to merge with %{defpo}") % {:defpo => defpo}
69:       $stderr.puts _("New .pot was copied to %{failed_filename}") %{:failed_filename => failed_filename}
70:       raise _("Check these po/pot-files. It may have syntax errors or something wrong.")
71:     else
72:       # update version and save merged data
73:       content.sub!(/(Project-Id-Version\:).*$/, "\\1 #{app_version}\\n\"")
74:       File.open(defpo, "w") {|f|f.write(content)}
75:     end
76:     
77:     self
78:   end
n_(msgid, msgid_plural, n = nil) click to toggle source
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] click to toggle source

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.

     # File lib/gettext.rb, line 179
179:   def ngettext(msgid, msgid_plural, n = nil)
180:     TextDomainManager.translate_plural_message(self, msgid, msgid_plural, n)
181:   end
Also aliased as: n_
np_(msgctxt, msgids, arg2 = nil, arg3 = nil) click to toggle source
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] click to toggle source

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.

     # File lib/gettext.rb, line 216
216:   def npgettext(msgctxt, msgids, arg2 = nil, arg3 = nil)
217:     if msgids.kind_of?(Array)
218:       msgid = msgids[0]
219:       msgid_ctxt = "#{msgctxt}\0004#{msgid}"
220:       msgid_plural = msgids[1]
221:       opt1 = arg2
222:       opt2 = arg3
223:     else
224:       msgid = msgids
225:       msgid_ctxt = "#{msgctxt}\0004#{msgid}"
226:       msgid_plural = arg2
227:       opt1 = arg3
228:       opt2 = nil
229:     end
230:     
231:     msgstr = TextDomainManager.translate_plural_message(self, msgid_ctxt, msgid_plural, opt1, opt2)
232:     if msgstr == msgid_ctxt
233:       msgid
234:     else
235:       msgstr
236:     end
237:   end
Also aliased as: np_
ns_(msgid, msgid_plural, n="|", seperator = "|") click to toggle source
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] click to toggle source

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.

     # File lib/gettext.rb, line 198
198:   def nsgettext(msgid, msgid_plural, n="|", seperator = "|")
199:     TextDomainManager.translate_plural_message(self, msgid, msgid_plural, n, seperator)
200:   end
Also aliased as: ns_
output_charset() click to toggle source

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

  • Returns: output_charset.

     # File lib/gettext.rb, line 267
267:   def output_charset
268:     TextDomainManager.output_charset
269:   end
output_charset=(charset) click to toggle source
Alias for: set_output_charset
p_(msgctxt, msgid) click to toggle source

This is the workaround to conflict p_ methods with the xx(“double x”) library. rubyforge.org/projects/codeforpeople/

Alias for: pgettext
pgettext(msgctxt, msgid) p_(msgctxt, msgid) click to toggle source

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

     # File lib/gettext.rb, line 161
161:   def pgettext(msgctxt, msgid)
162:     TextDomainManager.translate_singluar_message(self, "#{msgctxt}\0004#{msgid}", "\0004")
163:   end
Also aliased as: p_
rgettext(paths = nil, out = STDOUT) click to toggle source

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.

  • paths: An Array of po-file paths or nil.

  • out: output IO or output path.

  • Returns: self

     # File lib/gettext/tools/rgettext.rb, line 217
217:   def rgettext(paths = nil, out = STDOUT)
218:     RGetText.run(paths, out)
219:     self
220:   end
rmsgfmt(targetfile = nil, output_path = nil) click to toggle source

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.

    # File lib/gettext/tools/rmsgfmt.rb, line 77
77:   def rmsgfmt(targetfile = nil, output_path = nil)
78:     RMsgfmt.run(targetfile, output_path)
79:   end
rmsgmerge(reference = nil, definition = nil, out = STDOUT) click to toggle source

Experimental

     # File lib/gettext/tools/rmsgmerge.rb, line 482
482:   def rmsgmerge(reference = nil, definition = nil, out = STDOUT)
483:     RMsgMerge.run(reference, definition, out)
484:   end
s_(msgid, seperator = "|") click to toggle source
Alias for: sgettext
set_cgi(cgi_) click to toggle source

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

  • cgi_: CGI object

  • Returns: self

    # File lib/gettext/cgi.rb, line 20
20:   def set_cgi(cgi_)
21:     Locale.set_cgi(cgi_)
22:   end
set_current_locale(lang) click to toggle source

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

     # File lib/gettext.rb, line 283
283:   def set_current_locale(lang)
284:     Locale.current = lang
285:   end
Also aliased as: current_locale=
set_locale(lang) click to toggle source

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.

     # File lib/gettext.rb, line 274
274:   def set_locale(lang)
275:     Locale.set_app_language_tags(lang)
276:     Locale.default = lang
277:     Locale.current = lang
278:   end
Also aliased as: locale=, set_locale_all, setlocale
set_locale_all(lang) click to toggle source

for backward compatibility

Alias for: set_locale
set_output_charset(charset) click to toggle source

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

     # File lib/gettext.rb, line 260
260:   def set_output_charset(charset)
261:     TextDomainManager.output_charset = charset
262:     self
263:   end
Also aliased as: output_charset=
setlocale(lang) click to toggle source
Alias for: set_locale
sgettext(msgid, div = '|') s_(msgid, div = '|') click to toggle source

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

     # File lib/gettext.rb, line 144
144:   def sgettext(msgid, seperator = "|")
145:     TextDomainManager.translate_singluar_message(self, msgid, seperator)
146:   end
Also aliased as: s_
update_pofiles(textdomain, files, app_version, options = {}) click to toggle source

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 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)

     # File lib/gettext/tools.rb, line 121
121:   def update_pofiles(textdomain, files, app_version, options = {})
122:     puts options.inspect if options[:verbose]
123: 
124:     #write found messages to tmp.pot
125:     temp_pot = "tmp.pot"
126:     rgettext(files, temp_pot)
127: 
128:     #merge tmp.pot and existing pot
129:     po_root = options.delete(:po_root) || "po"
130:     FileUtils.mkdir_p(po_root)
131:     msgmerge("#{po_root}/#{textdomain}.pot", temp_pot, app_version, options.dup)
132: 
133:     #update local po-files
134:     only_one_language = options.delete(:lang)
135:     if only_one_language
136:       msgmerge("#{po_root}/#{only_one_language}/#{textdomain}.po", temp_pot, app_version, options.dup)
137:     else
138:       Dir.glob("#{po_root}/*/#{textdomain}.po") do |po_file|
139:         msgmerge(po_file, temp_pot, app_version, options.dup)
140:       end
141:     end
142: 
143:     File.delete(temp_pot)
144:   end
Also aliased as: update_pofiles_org
update_pofiles_org(textdomain, files, app_version, options = {}) click to toggle source
Alias for: update_pofiles

Private Instance Methods

array_to_cli_options(array) click to toggle source

convert an array of String/Symbol to cli options

     # File lib/gettext/tools.rb, line 164
164:   def array_to_cli_options(array)
165:     [*array].map do |o|
166:       o.kind_of?(Symbol) ? "--#{o}".gsub('_','-') : o.to_s
167:     end.join(' ')
168:   end
ensure_command_exists(cmd) click to toggle source
     # File lib/gettext/tools.rb, line 170
170:   def ensure_command_exists(cmd)
171:     `#{cmd} --help`
172:     unless $? && $?.success?
173:       raise _("`%{cmd}' can not be found. \nInstall GNU Gettext then set PATH or MSGMERGE_PATH correctly.") % {:cmd => cmd}
174:     end
175:   end
merge_po_files(po_a,po_b,msgmerge_options=[],verbose=false) click to toggle source

Merge 2 po files, using msgmerge

     # File lib/gettext/tools.rb, line 149
149:   def merge_po_files(po_a,po_b,msgmerge_options=[],verbose=false)
150:     return File.read(po_b) unless FileTest.exist? po_a
151: 
152:     cmd = ENV["MSGMERGE_PATH"] || "msgmerge"
153:     ensure_command_exists(cmd)
154: 
155:     remove_bom(po_a)
156: 
157:     cmd_params = array_to_cli_options(msgmerge_options)
158:     to_run = "#{cmd} #{cmd_params} #{po_a} #{po_b}"
159:     puts "\nrunning #{to_run}" if verbose
160:     `#{to_run}`
161:   end
mo_file_from_po_file(po_file,options) click to toggle source

where lies the mo file for a given po_file generare directory unless it exists

     # File lib/gettext/tools.rb, line 179
179:   def mo_file_from_po_file(po_file,options)
180:     options = {
181:       :mo_root => "./data/locale",
182:       :mo_path_rule => "%{lang}/LC_MESSAGES"
183:     }.merge(options)
184:     
185:     lang, textdomain = %[/([^/]+?)/(.*)\.po].match(po_file[options[:po_root].size..1]).to_a[1,2]
186: 
187:     mo_dir_rule = File.join(options[:mo_root], options[:mo_path_rule])
188:     mo_dir = mo_dir_rule % {:lang => lang}
189:     File.join(mo_dir, "#{textdomain}.mo")
190:   end

Disabled; run with --debug to generate this.

[Validate]

Generated with the Darkfish Rdoc Generator 1.1.6.