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

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

VERSION = "1.90.0"

Public Instance methods

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

  • msgid: the message id.
  • Returns: msgid.

[Source]

     # File lib/gettext.rb, line 310
310:   def N_(msgid)
311:     msgid
312:   end

This is same function as N_ but for ngettext.

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

[Source]

     # File lib/gettext.rb, line 318
318:   def Nn_(msgid, msgid_plural)
319:     [msgid, msgid_plural]
320:   end
_(msgid)

Alias for gettext

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

[Source]

     # File lib/gettext.rb, line 492
492:   def add_default_locale_path(path)
493:     TextDomain.add_default_locale_path(path)
494:   end

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.

[Source]

     # File lib/gettext.rb, line 82
 82:   def bindtextdomain(domainname, options = {}, locale_ = nil, charset = nil)
 83:     opt = {}
 84:     if options.kind_of? String
 85:       # For backward compatibility
 86:       opt = {:path => options, :locale => locale_, :charset => charset}
 87:     elsif options
 88:       opt = options
 89:     end
 90:     opt[:locale] = opt[:locale] ? Locale::Object.new(opt[:locale]) : Locale.get
 91:     opt[:charset] = TextDomainManager.output_charset if TextDomainManager.output_charset
 92:     opt[:locale].charset = opt[:charset] if opt[:charset]
 93:     Locale.set_current(opt[:locale])
 94:     target_key = bound_target
 95:     manager = @@__textdomainmanagers[target_key]
 96:     if manager
 97:       manager.set_locale(opt[:locale]) 
 98:     else
 99:       manager = TextDomainManager.new(target_key, opt[:locale])
100:       @@__textdomainmanagers[target_key] = manager
101:     end
102:     manager.add_textdomain(domainname, opt)
103:     manager
104:   end

Includes GetText module and bind a textdomain to a class.

[Source]

     # File lib/gettext.rb, line 110
110:   def bindtextdomain_to(klass, domainname, options = {}) 
111:     ret = nil
112:     klass.module_eval {
113:       include GetText
114:       ret = bindtextdomain(domainname, options)
115:     }
116:     ret
117:   end

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.

[Source]

    # File lib/gettext.rb, line 39
39:   def cached=(val)
40:     @@__cached = val
41:     GetText::TextDomain.check_mo = ! val
42:   end

Return the cached value.

[Source]

    # File lib/gettext.rb, line 45
45:   def cached?
46:     @@__cached
47:   end

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

  • Returns: the CGI object

[Source]

    # File lib/gettext/cgi.rb, line 36
36:   def cgi
37:     Locale.cgi
38:   end

Same as GetText.set_cgi.

  • cgi_: CGI object
  • Returns: cgi_

[Source]

    # File lib/gettext/cgi.rb, line 29
29:   def cgi=(cgi_)
30:     set_cgi(cgi_)
31:     cgi_
32:   end

Clear the cached messages.

[Source]

    # File lib/gettext.rb, line 50
50:   def clear_cache
51:     @@__cache_msgids = {}
52:     @@__cache_nmsgids = {}
53:     @@__cache_target_classes = {}
54:     @@__cache_bound_target = {}
55:     @@__cache_bound_targets = {}
56:   end

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.

[Source]

     # File lib/gettext/utils.rb, line 89
 89:   def create_mofiles(verbose = false, 
 90:                      podir = "./po", targetdir = "./data/locale", 
 91:                      targetpath_rule = "%s/LC_MESSAGES") 
 92: 
 93:     modir = File.join(targetdir, targetpath_rule)
 94:     Dir.glob(File.join(podir, "*/*.po")) do |file|
 95:       lang, basename = /\/([^\/]+?)\/(.*)\.po/.match(file[podir.size..-1]).to_a[1,2]
 96:       outdir = modir % lang
 97:       FileUtils.mkdir_p(outdir) unless File.directory?(outdir)
 98:       rmsgfmt(file, File.join(outdir, "#{basename}.mo"))
 99:       if verbose
100:         $stderr.puts %Q[#{file} -> #{File.join(outdir, "#{basename}.mo")}]
101:       end
102:     end
103:   end

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.

[Source]

     # File lib/gettext.rb, line 501
501:   def current_textdomain_info(options = {})
502:     opts = {:with_messages => false, :with_paths => false, :out => STDOUT}.merge(options)
503:     ret = nil
504:     each_textdomain {|textdomain|
505:       opts[:out].puts "TextDomain name: \"#{textdomain.name}\""
506:       opts[:out].puts "TextDomain current locale: \"#{textdomain.current_locale}\""
507:       opts[:out].puts "TextDomain current mo filename: \"#{textdomain.current_mo.filename}\""
508:       if opts[:with_paths]
509:         opts[:out].puts "TextDomain locale file paths:"
510:         textdomain.locale_paths.each do |v|
511:           opts[:out].puts "  #{v}"
512:         end
513:       end
514:       if opts[:with_messages]
515:         opts[:out].puts "The messages in the mo file:"
516:         textdomain.current_mo.each{|k, v|
517:           opts[:out].puts "  \"#{k}\": \"#{v}\""
518:         }
519:       end
520:     }
521:   end

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.

[Source]

     # File lib/gettext.rb, line 243
243:   def gettext(msgid)
244:     sgettext(msgid, nil)
245:   end

Gets the current locale.

[Source]

     # File lib/gettext.rb, line 484
484:   def locale
485:     Locale.current
486:   end

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.

[Source]

     # File lib/gettext.rb, line 454
454:   def locale=(locale)
455:     Locale.default = locale
456:     set_locale_all(locale)
457:     Locale.default
458:   end

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

[Source]

    # File lib/gettext/utils.rb, line 44
44:   def msgmerge(defpo, refpo, app_version) 
45:     $stderr.puts defpo
46:     cmd = ENV["MSGMERGE_PATH"] || "msgmerge"
47: 
48:     cont = ""
49:     if FileTest.exist? defpo
50:       cont = `#{cmd} #{defpo} #{refpo}`
51:     else
52:       File.open(refpo) do |io| 
53:         cont = io.read
54:       end
55:     end
56:     if cont.empty?
57:       failed_filename = refpo + "~"
58:       FileUtils.cp(refpo, failed_filename)
59:       $stderr.puts _("Failed to merge with %{defpo}") % {:defpo => defpo}
60:       $stderr.puts _("New .pot was copied to %{failed_filename}") %{:failed_filename => failed_filename}
61:       raise _("`#{cmd}' may not be found. \nInstall GNU Gettext then set PATH or MSGMERGE_PATH correctly.")
62:     else
63:       cont.sub!(/(Project-Id-Version\:).*$/, "\\1 #{app_version}\\n\"")
64:       File.open(defpo, "w") do |out|
65:         out.write(cont)
66:       end
67:     end
68:     self
69:   end
n_(arg1, arg2, arg3 = nil)

Alias for ngettext

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.

[Source]

     # File lib/gettext.rb, line 303
303:   def ngettext(arg1, arg2, arg3 = nil)
304:     nsgettext(arg1, arg2, arg3, nil)
305:   end
ns_(arg1, arg2, arg3 = "|", arg4 = "|")

Alias for nsgettext

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.

[Source]

     # File lib/gettext.rb, line 338
338:   def nsgettext(arg1, arg2, arg3 = "|", arg4 = "|")
339:     if arg1.kind_of?(Array)
340:       msgid = arg1[0]
341:       msgid_plural = arg1[1]
342:       n = arg2
343:       if arg3 and arg3.kind_of? Numeric
344:         raise ArgumentError, _("3rd parmeter is wrong: value = %{number}") % {:number => arg3}
345:       end
346:       div = arg3
347:     else
348:       msgid = arg1
349:       msgid_plural = arg2
350:       n = arg3
351:       div = arg4
352:     end
353: 
354:     cached_key = [bound_target, Locale.current, msgid + "\000" + msgid_plural]
355:     msgs = nil
356:     if @@__cached
357:       if @@__cache_nmsgids.has_key?(cached_key)
358:         msgs = @@__cache_nmsgids[cached_key]  # [msgstr, cond_as_string]
359:       end
360:     end
361:     unless msgs
362:       # Use "for"(not "each") to support JRuby 1.1.0.
363:       for target in bound_targets(self)
364:         manager = @@__textdomainmanagers[target]
365:         for textdomain in manager.textdomains
366:           msgs = textdomain[1].ngettext_data(msgid, msgid_plural)
367:           break if msgs
368:         end
369:         break if msgs
370:       end
371:       msgs = [[msgid, msgid_plural], "n != 1"] unless msgs
372:       @@__cache_nmsgids[cached_key] = msgs
373:     end
374:     msgstrs = msgs[0]
375:     if div and msgstrs[0] == msgid
376:       if index = msgstrs[0].rindex(div)
377:         msgstrs[0] = msgstrs[0][(index + 1)..-1]
378:       end
379:     end
380:     plural = eval(msgs[1])
381:     if plural.kind_of?(Numeric)
382:       ret = msgstrs[plural]
383:     else
384:       ret = plural ? msgstrs[1] : msgstrs[0]
385:     end
386:     ret
387:   end

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

[Source]

     # File lib/gettext.rb, line 478
478:   def output_charset
479:     TextDomainManager.output_charset || locale.charset
480:   end

Same as GetText.set_output_charset

[Source]

     # File lib/gettext.rb, line 472
472:   def output_charset=(charset)
473:     TextDomainManager.output_charset = charset
474:   end

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

[Source]

     # File lib/gettext/rgettext.rb, line 259
259:   def rgettext(targetfiles = nil, out = STDOUT)
260:     RGetText.run(targetfiles, out)
261:     self
262:   end

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.

[Source]

    # File lib/gettext/rmsgfmt.rb, line 79
79:   def rmsgfmt(targetfile = nil, output_path = nil)
80:     RMsgfmt.run(targetfile, output_path)
81:   end

Experimental

[Source]

     # File lib/gettext/rmsgmerge.rb, line 489
489:   def rmsgmerge(reference = nil, definition = nil, out = STDOUT)
490:     RMsgMerge.run(reference, definition, out)
491:   end
s_(msgid, div = '|')

Alias for sgettext

Sets a CGI object.

  • cgi_: CGI object
  • Returns: self

[Source]

    # File lib/gettext/cgi.rb, line 22
22:   def set_cgi(cgi_)
23:     Locale.set_cgi(cgi_)
24:   end

Sets the current locale to the current class/module

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

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

  • Returns: self

[Source]

     # File lib/gettext.rb, line 397
397:   def set_locale(locale, this_target_only = false)
398:     ret = nil
399:     if locale
400:       if locale.kind_of? Locale::Object
401:         ret = locale
402:       else
403:         ret = Locale::Object.new(locale.to_s)
404:       end
405:       ret.charset = TextDomainManager.output_charset if TextDomainManager.output_charset
406:       Locale.set(ret)
407:     else
408:       Locale.set(nil)
409:       ret = Locale.get
410:     end
411:     if this_target_only
412:       manager = @@__textdomainmanagers[bound_target]
413:       if manager
414:         manager.set_locale(ret, ! cached?)
415:       end
416:     else
417:       each_textdomain {|textdomain|
418:         textdomain.set_locale(ret, ! cached?)
419:       }
420:     end
421:     self
422:   end

Sets current locale to the all textdomains.

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

[Source]

     # File lib/gettext.rb, line 429
429:   def set_locale_all(locale)
430:     ret = nil
431:     if locale
432:       if locale.kind_of? Locale::Object
433:         ret = locale
434:       else
435:         ret = Locale::Object.new(locale.to_s)
436:       end
437:     else
438:       ret = Locale.default
439:     end
440:     ret.charset = TextDomainManager.output_charset if TextDomainManager.output_charset
441:     Locale.set_current(ret)
442:     TextDomainManager.each_all {|textdomain|
443:       textdomain.set_locale(ret, ! cached?)
444:     }
445:     self
446:   end

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

[Source]

     # File lib/gettext.rb, line 464
464:   def set_output_charset(charset)
465:     TextDomainManager.output_charset = charset
466:     self
467:   end
setlocale(locale)

Alias for locale=

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

[Source]

     # File lib/gettext.rb, line 259
259:   def sgettext(msgid, div = '|')
260:     cached_key = [bound_target, Locale.current, msgid]
261:     if cached?
262:       if @@__cache_msgids[cached_key]
263:         return @@__cache_msgids[cached_key]
264:       end
265:     end
266:     msg = nil
267: 
268:     # Use "for"(not "each") to support JRuby 1.1.0.
269:     for target in bound_targets(self)
270:       manager = @@__textdomainmanagers[target]
271:       for textdomain in manager.textdomains
272:         msg = textdomain[1].gettext(msgid)
273:         break if msg
274:       end
275:       break if msg
276:     end
277: 
278:     msg ||= msgid
279:     if div and msg == msgid
280:       if index = msg.rindex(div)
281:         msg = msg[(index + 1)..-1]
282:       end
283:     end
284:     @@__cache_msgids[cached_key] = msg
285:   end

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.

[Source]

     # File lib/gettext.rb, line 125
125:   def textdomain(domainname)
126:     domain = TextDomainManager.textdomain(domainname)
127:     raise NoboundTextDomainError, "#{domainname} is not bound." unless domain
128:     target_key = bound_target
129:     manager = @@__textdomainmanagers[target_key]
130:     unless manager
131:       manager = TextDomainManager.new(target_key, Locale.get)
132:       @@__textdomainmanagers[target_key] = manager
133:     end
134:     manager.set_locale(Locale.get)
135:     manager.add_textdomain(domainname)
136:     manager
137:   end

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.

[Source]

     # File lib/gettext.rb, line 143
143:   def textdomain_to(klass, domainname) 
144:     ret = nil
145:     klass.module_eval {
146:       include GetText
147:       ret = textdomain(domainname)
148:     }
149:     ret
150:   end

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

[Source]

     # File lib/gettext/utils.rb, line 120
120:   def update_pofiles(textdomain, files, app_version, po_root = "po", refpot = "tmp.pot")
121:     rgettext(files, refpot)
122:     msgmerge_all(textdomain, app_version, po_root, refpot)
123:     File.delete(refpot)
124:   end

[Validate]