= gettext - Ruby-GetText-Package

Ruby-GetText-Package is a Localization(L10n) library and tool  
which is modeled after the GNU gettext package.

This library translates original messages to localized  
messages using client-side locale information(environment  
variable or CGI variable).

The tools for developers support creating, useing, and modifying  
localized message files(message catalogs).

((*Rails*))
Rails support has been removed.  
Rails / ActiveRecord specific code now lives in locale_rails[http://github.com/mutoh/locale_rails/tree/master], gettext_rails[http://github.com/mutoh/gettext_rails/tree/master] and gettext_activerecord[http://github.com/mutoh/gettext_activerecord/tree/master].

== Website
* homepage[http://www.yotabanana.com/hiki/ruby-gettext.html]
* on rubyforge[http://gettext/rubyforge.org/]
* on github[http://github.com/gettext/]

== Features
* Translate singular/plural messages with simple APIs(similar to GNU gettext)

* Thread safety. Message resources are shared from all threads, but 
  returns translated messages of the current thread's locale.

* Tools to find message IDs
  * Extract message IDs to po-files using rgettext from 
    * ruby scripts 
    * glade-2 XML file(.glade)
    * ERB file(.rhtml, .erb)
    * Anything (with your own parsers)
    * The po-files are compatible to GNU gettext.

  * rmsgfmt creates a mo-file from a po-file.
    The mo-file is compatible to GNU gettext(msgfmt).

  * Using rgettext/rmsgfmt as Rake tasks

* textdomain's scope is adapt to ruby class/module mechanism.
  * A class/module can have plural textdomains.
  * a message is looked up in its class/module and ancestors.

* CGI support (gettext/cgi)
  * Locale is retrieved from client informations using Ruby-Locale.
    (HTTP_ACCEPT_LANGUAGE, HTTP_ACCEPT_CHARSET, QUERY_STRING(lang), Cookies(lang)).

* String%() is extended to use named argument such as <tt>%{foo}" %{:foo => 1}</tt>.
  Notes that Ruby-1.9.x supports this format by itself.

== Requirements
* {Ruby 1.8.3 or later}[http://www.ruby-lang.org]
* {Rubygems}[http://www.rubygems.org/]
* {locale gem}[http://rubyforge.org/projects/locale/]
  * $ gem install locale
* (for development only)
  * {GNU gettext 0.10.35 or later}[http://www.gnu.org/software/gettext/gettext.html]
  * {Racc-1.4.3 or later}[http://www.ruby-lang.org/raa/list.rhtml?name=racc]
    * (for compiling src/rmsgfmt.ry only)

== Install
* Uninstall old gettext if exists. (You need to do this when updating 1.93.0 -> 2.0.1)
    (sudo/su on POSIX system)
    gem uninstall gettext

* gem
    #from rubyforge 
    (sudo/su on POSIX system)
    gem install gettext

* download tar-ball
    # De-Compress archive and enter its top directory.
    (sudo/su on POSIX system)
    ruby setup.rb

You can also install files in your favorite directory by  
supplying setup.rb some options. Try <tt>ruby setup.rb --help</tt>.

== Usage
===Translation
- _: Basic translation method
  Translates the message.
    _("Hello")

The gettext methods comes in 3 combinable flavors
- n: Pluralized
  Returns singular or plural form, depending on how many you have.
    n_("Apple", "%{num} Apples", 3)
    n_(["Apple", "%{num} Apples"], 3)

- p: context aware
  A context is a prefix to your translation, usefull when one word has different meanings, depending on its context.
    p_("Printer","Open") <=> p_("File","Open")
    is the same as s_("Printer|Open")  <=> s_("File|Open")

- s: without context
  If a translation could not be found, return the msgid without context.
    s_("Printer|Open") => "Öffnen" #translation found
    s_("Printer|Open") => "Open"   #translation not found

- combinations
    np_("Fruit", "Apple", "%{num} Apples", 3)
    ns_("Fruit|Apple","%{num} Apples", 3)

    np_(["Fruit","Apple","%{num} Apples"], 3)
    ns_(["Fruit|Apple","%{num} Apples"], 3)

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

    fruit = N_("Apple")   # same as fruit = "Apple"
    _(fruit)              # does a normal translation

    fruits = Nn_("Apple", "%{num} Apples")
    n_(fruits, 3)

=== Bind textdomains to the classes.
A textdomain has a translation file in each language.
A module/class can have multi textdomains. This means the 
libraries/applications can have their own textdomains.

 class Foo
   include GetText
   bindtextdomain "your_app_domain_name"
 end

 class Book
   include GetText
   bindtextdomain "general"
   bindtextdomain "book"
 end

=== Locale
If you need to set the locale by yourself, then use:
  GetText.locale = "en_US" # translate into english from now on
  GetText.locale # => en_US
Or
  include GetText
  set_locale "en_US"

For more details and options, have a look at the samples folder or
consult the tutorial[http://www.yotabanana.com/hiki/ruby-gettext-howto.html].

== License
This program is licenced under the same licence as Ruby(See COPYING) or 
LGPL(Lesser General Public License: http://www.gnu.org/licenses/lgpl-3.0.txt).  

* mofile.rb
  * Copyright (C) 2001-2009 Masao Mutoh <mutoh at highwhay.ne.jp>
  * Copyright (C) 2001,2002 Masahiro Sakai <s01397ms at sfc.keio.ac.jp>

* gettext.rb
  * Copyright (C) 2001-2009 Masao Mutoh <mutoh at highwhay.ne.jp>
  * Copyright (C) 2001,2002 Masahiro Sakai <s01397ms at sfc.keio.ac.jp>

* rgettext 
  * Copyright (C) 2001-2009 Masao Mutoh <mutoh at highwhay.ne.jp>
  * Copyright (C) 2001,2002 Yasushi Shoji <yashi at atmark-techno.com>

* setup.rb
  * Copyright (C) 2000-2005 Minero Aoki <aamine at loveruby.net>
  * This file is released under LGPL. See the top of the install.rb.

* Others
  * Copyright (C) 2001-2009 Masao Mutoh <mutoh at highwhay.ne.jp>


== Translators
* Bosnian(bs)                - Sanjin Sehic <saserr at gmail.com>
* Bulgarian(bg)              - Sava Chankov <sava.chankov at gmail.com>
* Catalan(ca)                - Ramon Salvadó <rsalvado at gnuine.com>
* Chinese(Simplified)(zh_CN)
  * Yang Bob <bob.yang.dev at gmail.com> (current)
  * Yingfeng <blogyingfeng at gmail.com>
* Chinese(Traditional)(zh_TW)
  * Yang Bob <bob.yang.dev at gmail.com> (current)
  * LIN CHUNG-YI <xmarsh at gmail.com>
* Croatian(hr)               - Sanjin Sehic <saserr at gmail.com>
* Czech(cs)                  - Karel Miarka <kajism at yahoo.com>
* Dutch(nl)                  - Menno Jonkers <ruby-gettext at jonkers.com>
* Esperanto(eo)              - Malte Milatz <malte at gmx-topmail.de>
* Estonian(et)               - Erkki Eilonen <erkki at itech.ee>
* French(fr)
  * Vincent Isambart <vincent.isambart at gmail.com> (current)
  * David Sulc <davidsulc at gmail.com>
  * Laurent Sansonetti <laurent.sansonetti at gmail.com>
* German(de)
  * Patrick Lenz <patrick at limited-overload.de> (current)
  * Detlef Reichl <detlef.reichl at gmx.org>
  * Sven Herzberg <herzi at abi02.de>
  * Sascha Ebach <se at digitale-wertschoepfung.de>
* Greek(el)                  - Vassilis Rizopoulos <damphyr at gmx.net>
* Hungarian(hu)              - Tamás Tompa <tompata at gmail.com>
* Italian(it)
  * Marco Lazzeri <marco.lazzeri at gmail.com>
  * Gabriele Renzi <surrender_it at yahoo.it>
* Japanese(ja)               - Masao Mutoh <mutomasa at gmail.com>
* Korean(ko)                 - Gyoung-Yoon Noh <nohmad at gmail.com>
* Latvian(lv)                - Aivars Akots <aivars.akots at gmail.com>
* Norwegian(nb)              - Runar Ingebrigtsen <runar at mopo.no>
* Portuguese(Brazil)(pt_BR)  
  * Antonio S. de A. Terceiro <terceiro at softwarelivre.org> (current)
  * Joao Pedrosa <joaopedrosa at gmail.com>
* Russian(ru)                - Yuri Kozlov <kozlov.y at gmail.com>
* Serbian(sr)                - Slobodan Paunović" <slobodan.paunovic at gmail.com>
* Spanish(es)
  * David Espada <davinci at escomposlinux.org> (current)
  * David Moreno Garza <damog at damog.net>
* Swedish(sv)                - Nikolai Weibull <mailing-lists.ruby-talk at rawuncut.elitemail.org>
* Ukrainian(uk)              - Alex Rootoff <rootoff at pisem.net>
* Vietnamese(vi)             - Ngoc Dao Thanh <ngocdaothanh at gmail.com>

== Status of translations
* Bosnian(bs)               - 1.90.0 (old)
* Bulgarian(bg)             - 2.0.1
* Catalan(ca)               - 2.0.1
* Croatian(hr)              - 1.90.0 (old)
* Chinese(zh_CN)            - 2.0.1
* Chinese(zh_TW)            - 2.0.1
* Czech(cs)                 - 1.9.0 (old)
* Dutch(nl)                 - 1.90.0 (old)
* English(default)          - 2.1.0
* Esperanto(eo)             - 2.0.1
* Estonian(et)              - 2.0.1
* French(fr)                - 2.0.1 
* German(de)                - 2.0.1
* Greek(el)                 - 2.0.1 
* Hungarian(hu)             - 2.0.1
* Italian(it)               - 1.6.0 (old)
* Japanese(ja)              - 2.1.0
* Korean(ko)                - 1.9.0 (old)
* Latvian(lv)               - 2.0.1 
* Norwegian(nb)             - 2.0.1
* Portuguese(Brazil)(pt_BR) - 2.0.1
* Russian(ru)               - 2.0.1
* Serbian(sr)               - 2.0.1
* Spanish(es)               - 2.0.1
* Swedish(sv)               - 0.8.0 (too much old)
* Ukrainian(uk)             - 2.0.1
* Vietnamese(vi)            - 2.0.1

== Maintainer
Masao Mutoh <mutomasa at gmail.com>