Rubi18n

Rubi18n is a i18n tool to translate your Ruby application in several languages.

Features

If there isn’t translation in user locale, it will be found in locales, which user may know (not only in default locale). For example, many people in Belarus can understand Russian, and locale has information about it.
It can localize your application: format numbers to the rules of the user locale, translate month and week days name and give other locale information.
It has translation for commons words, like “OK”, “Cancel”, etc.
It storage translation in rich YAML format. You can put procedures and pluralization (“1 comment”, “5 comments”) in your translation.

How to

Create translations dir. For exmaple: YOUR_APP/translations/.

Add file with translation in some language. For example: YOUR_APP/translations/en.yml

post:
  add: Add post
  delete: Delete post %1

comments: !!pl
  0: No comments
  1: One comment
  n: %1 comments

author: !!proc |name| "This article was written by #{name.capitalize}"

Add Rubi18n::Mixin to your application. For example:

require "rubygems"
require "rubi18n"

class Application
  include Rubi18n::Mixin
  …
end

Set translations dir and autodetect user locale:

class Application
  def initialize
    translations_dir File.dirname(__FILE__) + "/translations/"
    set_locales ENV["LANG"]
  end
  …
end

Print translation string to user:

i18n.post.add                        #=> "Add post"
i18n.post.delete("Test")             #=> "Delete post Test"
i18n.strftime(post.created_at, "%B") #=> "September"
i18n.comments(1)                     #=> "6 comments"
i18n.comments(12)                    #=> "12 comments"
i18n.author("poet")                  #=> "This article was written by Poet"

Usage

Locale

All supported locales are storage in Rubi18n gem at locales dir. If you want to add your locale, please write me to [email protected] .

To get information about locale create Rubi18n::Locale instance:

en = Rubi18n::Locale.new("en")

To get first available user locale use Rubi18n::Locale.find methods. It will be looking also general language locale for dialect (if Canadian French (fr_CA) willn’t be available it return French (fr) locale).

locale = Rubi18n::Locale.new(locales_array)

You can get from locale:

Locale title and RFC 3066 code:

locale["title"] #=> "English"
locale["code"] #=> "en"

Language direction (left to right, or right to left for Arabic and Hebrew):
```
locale["direction"] #=> "ltr"
```
Week start day (“sunday” or “monday”)
```
locale["week_start"] #=> "sunday"
```

Translation

Translation files use YAML format and has name CODE.yml , where CODE is a language/country code (RFC 3066) like en_US. For example: en.yaml is a English translation, en_US.yml is a translation to USA English dialect.

In translation you can use:

Strings

robot: This is robot
percent: "Percent sign (%)"

Numbers
```
number: 123
float: 12.45
```

Pluralizable messages

robots: !!pl
  0: No robots
  1: One robot
  n: %1 robots

Procedures
```
sum: !!proc |x, y| x + y
```

To load translations use Rubi18n::Translation.load method with array with user locales codes. It will load all user locales and sublocales, which people in this locale offten understand.

i18n = Rubi18n::Translation.load(user_locales, DIR_WITH_TRANSLATIONS)

To get translated string use method with key name or square brackets [] for keys, which contain Object methods (class, inspect, etc):

i18n.robot    #=> "This is robot"
i18n["robot"] #=> "This is robot"

Translation may be hierarchical:

i18n.post.add       #=> "Add post"
i18n["post"]["add"] #=> "Add post"

If locale willn’t be found in user locale Rubi18n will search it in another locale, which user know and they sublocales:

i18n.no.in.english #=> "В английском нет"

Translated string has locale method and you can get it locale (Locale instance or code string if locale is’t supported in Rubi18n):

i18n.no.in.english.locale #=> Locale ru (Русский)

You can replace some parameters in translated string by put it as arguments:

name: "My name is %1"

i18n.name("John") #=> "My name is John"

Pluralizable messages get item count from first argument. Or from next if you pluralize several parameters (see spec/translation_spec.rb and spec/translation/general/en.yml for samples).

i18n.robots(0)  #=> "No robots"
i18n.robots(1)  #=> "One robot"
i18n.robots(50) #=> "50 robots"

If there isn’t pluralization for some number (for example, 0), translation will be use ‘n’. If there isn’t locale file for translation for pluralization will be using default (English) rule.

Rub18n already has translation for common words for most supported locales. See base/ in dir in gem.

Formatters

You can print number and float according to the rules of the locale by to_ls method:

12000.to_ls  #=> "12,000"
15.34.to_ls  #=> "15.34"

Number and float formatters will also put real typographic minus and put non-break thin spaces (for locale, which use it as digit separator).

To translate month and week day names use Rubi18n::Translation.strftime method:

i18n.strftime(Time.now, "%A", %d/%B")  #=> "Tuesday, 09 September"

You can put format string to strftime method in translation file to get locale specific time:

translations/en.yml

published: "%A, %d/%B"

application.rb

i18n.strftime(Time.now, i18n.published)

License

Rubi18n is licensed under the GNU Lesser General Public License version 3. You can read it in LICENSE file or in www.gnu.org/licenses/gpl.html.

Author

Andrey “A.I.” Sitnik <[email protected]>