gettext 1.1.1 → 1.2.0

data/lib/gettext.rb

@@ -10,7 +10,7 @@
   You may redistribute it and/or modify it under the same
   license terms as Ruby.
 
-  $Id: gettext.rb,v 1.5 2005/11/30 17:59:14 mutoh Exp $
+  $Id: gettext.rb,v 1.8 2006/02/20 12:35:06 mutoh Exp $
 =end
 
 require 'rbconfig'
@@ -21,67 +21,147 @@ require 'gettext/textdomain'
 require 'gettext/string'
 
 module GetText
+  # If the textdomain isn't bound when calling GetText.textdomain, this error is raised.
   class NoboundTextDomainError < RuntimeError
   end
 
   @@__textdomain = Hash.new
   @@__textdomain_key = Hash.new
 
-  @@output_charset = nil
-  @@locale = nil
+  @@__output_charset = nil
 
-  def bindtextdomain(domainname, path = nil, locale = nil, charset = nil)
-    if @@locale
-      locale = @@locale
-      Locale.set(Locale::CTYPE, locale)
+  # 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.
+  # * 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::TextDomain.
+  #
+  def bindtextdomain(domainname, path = nil, locale_ = nil, charset = nil)
+    locale = locale_ ? Locale::Object.new(locale_) : Locale.get
+    if @@__output_charset
+      # Set global setting forcely.
+      charset = @@__output_charset
     else
-      locale ||= Locale.get
-    end
-    if @@output_charset
-      charset = @@output_charset
-    else
-      charset ||= ENV["OUTPUT_CHARSET"] ? ENV["OUTPUT_CHARSET"] : Locale.codeset
-      @@output_charset = charset
+      charset = ENV["OUTPUT_CHARSET"] if ENV["OUTPUT_CHARSET"]
+      @@__output_charset = charset
     end
+    locale.charset = charset if charset
+    Locale.set_current(locale)
+
     src = callersrc
-    $stderr.print "bind the domain '#{domainname}' to '#{src}'. charset is #{charset}\n" if $DEBUG
+    $stderr.print "bind the domain '#{domainname}' to '#{src}'. locale is #{locale.inspect}\n" if $DEBUG
     textdomain = @@__textdomain[src]
     unless textdomain
       textdomain = @@__textdomain_key[domainname]
       @@__textdomain[src] = textdomain
     end
 
-    if ! textdomain or ! textdomain.same_property?(domainname, path, locale, charset)
-      textdomain = TextDomain.new(domainname, path, locale, charset)
+    textdomain.set_locale(locale) if textdomain
+
+    if ! textdomain or ! textdomain.same_property?(domainname, path, locale)
+      textdomain = TextDomain.new(domainname, path, locale)
       @@__textdomain_key[domainname] = textdomain
       @@__textdomain[src] = textdomain
     end
     @@__textdomain[src]
   end
 
+  # Binds a existed textdomain to your program. 
+  # This is the same function with GetText.bindtextdomain but simpler 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::TextDomain.
   def textdomain(domainname)
     src = callersrc
     textdomain = @@__textdomain_key[domainname]
     raise NoboundTextDomainError, "#{domainname} is not bound." unless textdomain
+    textdomain.set_locale(Locale.current)
     @@__textdomain[src] = textdomain
-    $stderr.print "Use the domain '#{domainname}' to '#{src}'. charset is #{textdomain.charset}\n" if $DEBUG
+    $stderr.print "Use the domain '#{domainname}' to '#{src}'. locale is #{textdomain.current_locale.inspect}\n" if $DEBUG
     @@__textdomain[src]
   end
-  
+
+  # call-seq:
+  #   gettext(msgid)
+  #   _(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.
   def gettext(msgid)
     textdomain = @@__textdomain[callersrc]
     textdomain ? textdomain.gettext(msgid) : msgid
   end
   
-  def ngettext(msgid, msgid_plural, n)
+  # call-seq:
+  #   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.
+  def ngettext(arg1, arg2, arg3 = nil)
+    if arg1.kind_of?(Array)
+      msgid = arg1[0]
+      msgid_plural = arg1[1]
+      n = arg2
+    else
+      msgid = arg1
+      msgid_plural = arg2
+      n = arg3
+    end
     textdomain = @@__textdomain[callersrc]
-    textdomain ? textdomain.ngettext(msgid, msgid_plural, n) : (n == 1 ? msgid : msgid_plural)
+    textdomain.ngettext(msgid, msgid_plural, n)
   end
-  
+
+  # This function does nothing. But it is required in order to recognize the msgid by rgettext.
+  # * msgid: the message id.
+  # * Returns: msgid.
   def N_(msgid)
     msgid
   end
 
+  # This is same function as N_ but for ngettext. 
+  # * msgid: the message id.
+  # * Returns: msgid.
+  def Nn_(msgid, msgid_plural)
+    [msgid, msgid_plural]
+  end
+
+  # call-seq:
+  #   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: http://www.gnu.org/software/gettext/manual/html_mono/gettext.html#SEC151
   def sgettext(msgid, div = '|')
     textdomain = @@__textdomain[callersrc]
     if textdomain
@@ -97,44 +177,112 @@ module GetText
     msg
   end
 
-  def callersrc
+  def callersrc # :nodoc:
     caller(2)[0].sub(/:\d+(?::in \`\S+\')?\Z/, '')
   end
 
+  # Sets locale(String) such as "de", "fr", "it", "ko", "ja_JP.eucJP", "zh_CN.EUC" ... 
+  #
+  # Notice that you shouldn't use this for your own Libraries.
+  # * locale: a locale string
+  # * src: internal usage only. You shouldn't use this.
+  # * Returns: self
+  def set_locale(locale, src = callersrc)
+    if locale
+      ret = Locale::Object.new(locale)
+      ret.charset = @@__output_charset if @@__output_charset
+    else
+      ret = nil
+    end
+    Locale.set_current(ret)
+
+    textdomain = @@__textdomain[src]
+    textdomain.set_locale(ret, true) if textdomain
+
+    self
+  end
+
+  # Same as GetText.set_locale.
+  # * locale: a locale string
+  # * src: internal usage only. You shouldn't use this.
+  # * Returns: a locale string
   def locale=(locale)
-    @@locale = locale
-    textdomain = @@__textdomain[callersrc]
-    textdomain.set_locale(locale) if textdomain
+    set_locale(locale, callersrc)
     locale
   end
 
+  # 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 in your own Libraries.
+  # * charset: an output_charset
+  # * Returns: charset
+  def set_output_charset(charset)
+    @@__output_charset = charset
+    self
+  end
+
+  # Same as GetText.set_output_charset
+  # * charset: an output_charset
+  # * Returns: charset
   def output_charset=(charset)
-    @@output_charset = charset
+    @@__output_charset = charset
   end
 
+  # Gets the current output_charset which is set using GetText.set_output_charset.
+  # * Returns: output_charset.
   def output_charset
-    @@output_charset
+    @@__output_charset
   end
 
+  # Gets the current locale.
+  # * Returns: a current Locale::Object
   def locale
-    @@locale
+    Locale.current
   end
 
+  # Sets a charset(String) such as "euc-jp", "sjis", "CP932", "utf-8", ... 
+  # This affect he current textdomain only. 
+  # Generaly you should use GetText.output_charset= instead. 
+  # And you shouldn't use this in your own Libraries.
+  # * charset: an charset
+  # * src: internal usage only. You shouldn't use this.
+  # * Returns: self
+  def set_charset(cs, src = callersrc)
+    textdomain = @@__textdomain[src]
+    if textdomain
+      locale = textdomain.current_locale
+      locale ||= Locale.current
+      locale.charset = cs if locale
+      textdomain.set_locale(locale, true)
+      Locale.set_current(locale)
+    end
+    self
+  end
+
+  # Same as GetText.set_charset.
+  # * charset: an charset
+  # * Returns: charset
   def charset=(cs)
-    textdomain = @@__textdomain[callersrc]
-    textdomain.set_charset(cs) if textdomain
+    set_charset(cs, callersrc)
+    cs
   end
   
-  alias :setlocale :locale=
-  alias :set_locale :locale=
-  alias :set_output_charset :output_charset=
-  alias :_ :gettext
-  alias :n_ :ngettext
-  alias :s_ :sgettext
+  # 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
+  def add_default_locale_path(path)
+    TextDomain.add_default_locale_path(path)
+  end
+
+  alias :setlocale :locale= #:nodoc:
+  alias :_ :gettext   #:nodoc:
+  alias :n_ :ngettext #:nodoc:
+  alias :s_ :sgettext #:nodoc:
 
   module_function :bindtextdomain, :textdomain, 
     :N_, :gettext, :_, :ngettext, :n_, 
     :sgettext, :s_, :callersrc,
-    :setlocale, :set_locale, :locale=, :locale, :charset=,
+    :setlocale, :set_locale, :locale=, :locale, :charset=, :set_charset,
     :set_output_charset, :output_charset=, :output_charset
 end

data/lib/gettext/cgi.rb

@@ -6,93 +6,59 @@
   You may redistribute it and/or modify it under the same
   license terms as Ruby.
 
-  $Id: cgi.rb,v 1.4 2005/12/07 17:09:39 mutoh Exp $
+  $Id: cgi.rb,v 1.6 2006/02/20 12:35:06 mutoh Exp $
 =end
 
 require 'cgi'
 require 'gettext'
+require 'gettext/locale_cgi'
 
 module Locale
-  alias :orig_get :get
-  alias :orig_set :set
-
-  @@cgi = nil
-  @@locale_cgi = nil
-
   module_function
-  def cgi=(cgi)
-    @@cgi = cgi
-  end
-
-  def cgi
-    @@cgi = CGI.new unless @@cgi
-    @@cgi
+  # Sets a CGI object.
+  # * cgi_: CGI object
+  # * Returns: self
+  def set_cgi(cgi_)
+    @@locale_system_module.set_cgi(cgi_)
+    self
   end
 
-  def normalize(lang)
-    lang = lang.split(',').first.gsub(/_/, "-").split('-') rescue []
-    language = lang[0]
-    dialect  = lang[1]
-    language = language ? language.downcase : 'en' # default is en
-    dialect  = dialect ? "_#{dialect.upcase}" : ""
-    ret = "#{language}#{dialect}" 
+  # Sets a CGI object.
+  # * cgi_: CGI object
+  # * Returns: cgi_ 
+  def cgi=(cgi_)
+    set_cgi(cgi_)
+    cgi_
   end
 
-  def get(lctype = Locale::CTYPE) #lctype doesn't used here.
-    ret = @@locale_cgi
-    unless ret
-      @@cgi = CGI.new unless @@cgi
-      if ret = @@cgi["lang"] and ret.size > 0
-	$stderr.print "query_string: lang = #{ret}\n" if $DEBUG
-      elsif ret = @@cgi.cookies["lang"][0]
-	$stderr.print "cookie: lang = #{ret}\n" if $DEBUG
-      elsif lang = @@cgi.accept_language
-	$stderr.print "accept lanaugage: lang = #{lang}\n" if $DEBUG
-	ret = normalize(lang)
-      else
-	ret = "en"
-      end
-    end
-    $stderr.print "Locale.get = #{ret}\n" if $DEBUG
-    ret
+  # Gets the CGI object. If it is nil, returns new CGI object.
+  # * Returns: the CGI object
+  def cgi
+    @@locale_system_module.cgi
   end
+end
 
-  def set(lctype, loc)
-    # Override this method. Because the value from WWW browser doesn't
-    # match to the locale strings of POSIX setlocale.
-    @@locale_cgi = loc
-  end
+module GetText
+  module_function
 
-  def codeset
-    @@cgi = CGI.new unless @@cgi
-    codesets = @@cgi.accept_charset
-    if codesets
-      ary = codesets.split(',')
-      ary[0]
-    else
-      "UTF-8"
-    end
+  # Sets a CGI object.
+  # * cgi_: CGI object
+  # * Returns: self
+  def set_cgi(cgi_)
+    Locale.set_cgi(cgi_)
   end
 
-  alias :charset :codeset
-  alias :setlocale :set
-  alias :set_cgi :cgi=
-
-  module_function :charset, :set_cgi, :set, :setlocale
-end
-
-module GetText
-  def cgi=(cgi)
-    @cgi = cgi
-    Locale.cgi = cgi
+  # Same as GetText.set_cgi.
+  # * cgi_: CGI object
+  # * Returns: cgi_
+  def cgi=(cgi_)
+    set_cgi(cgi_)
+    cgi_
   end
 
+  # Gets the CGI object. If it is nil, returns new CGI object.
+  # * Returns: the CGI object
   def cgi
-    @cgi = Locale.cgi unless @cgi
-    @cgi
+    Locale.cgi
   end
-
-  alias :set_cgi :cgi=
-
-  module_function :cgi=, :set_cgi, :cgi
 end

data/lib/gettext/container.rb

@@ -1,28 +1,37 @@
 =begin
   gettext/erb.rb - Class-based container module for GetText 
 
-  Copyright (C) 2005  Masao Mutoh
+  Copyright (C) 2005,2006  Masao Mutoh
 
   You may redistribute it and/or modify it under the same
   license terms as Ruby.
 
-  $Id: container.rb,v 1.3 2005/08/22 17:24:33 mutoh Exp $
+  $Id: container.rb,v 1.4 2006/02/23 14:53:59 mutoh Exp $
 =end
 
 require 'gettext'
 
 module GetText
+  # This module is used instead of GetText module. This module provides same functions as GetText module.
+  #
+  # Normaly, GetText.bindtexdomain should be called once a ruby-script-file.
+  # But if the class includes GetText::Container, a TextDomain is bound to an instance of the class. 
+  # So you don't need to call bindtextdomain in each files if the files define a class.
+  # 
+  # This module is useful for application-side classes, but you shouldn't use this for libraries. 
+  # Because the user of your library may override/add new features to the original library and the 
+  # user needs to prepare another TextDomain(Otherwise, apply po/mo patch to the original library).
   module Container
     include GetText
 
-    alias :_bindtextdomain :bindtextdomain
+    alias :_bindtextdomain :bindtextdomain #:nodoc:
 
-    def bindtextdomain(domainname, path = nil, locale = nil, charset = nil)    
+    def bindtextdomain(domainname, path = nil, locale = nil, charset = nil) #:nodoc:
       @gettext_container_domainname = domainname
       _bindtextdomain(domainname, path, locale, charset)
     end
 
-    def callersrc
+    def callersrc #:nodoc:
       @gettext_container_domainname
     end