Gettext Localize

This plugin is intended to help you localize your rails app using Gettext, it doesn't try to cover localization of models. It works with Rails 2.0 and 2.1 and has been tested with: catalan, spanish, english, french, german.

It will not work with Rails >= 2.2 until gettext gem has been updated (> 1.9.3)

Features

• loads ruby-gettext with meaningful defaults, that can be overwritten at different levels
• simplifies translation with rake tasks
• set the locale in the controllers by query param, session, cookie or browser header
• translates dates and date helpers
• translates currencies and other text helpers
• translation entirely done with gettext, no per language ruby code

Installation

sudo gem install gettext
script/plugin install git://github.com/grosser/gettext_localize.git

Workflow

• localize your app texts adding the gettext function _("Welcome to our homepage") wherever you want translated text

Choose your locales

You can have multiple translations per language (en_US + en_UK) or only a single ('en')

Po files

All translations are stored in a human-reable format, inside the po/app.pot.
To start translation of a new locale, copy this file to po/LOCALE/app.po.
To create an initial .pot file rake gettext:updatepo.

gettext:updatepo will search through all your application files and store the found translations in the po/pot files.

Unfound translations?

• add them to an easy-to-parse file inside your app folder #unfound_translations.rb ('my missing translation') ('missing...') so they can be found on the next run
• modify the gettext:updatepo task, to look in different folders
• use gettext_test_log rails plugin to find all translations used while testing

Mo files

After you have finished translating, write machine-readable translation files.
rake gettext:makemo

Recognize the users locale

• define defaults in your environment.rb
• gettext_localize tries to find locale in params/cookie/session/header by default

Sample Configuration

Put this into config/environment.rb or an initializer

if defined? GettextLocalize
  GettextLocalize::app_name = 'app'
  GettextLocalize::app_version = '1.2.0'
  GettextLocalize::default_locale = 'en_UK' #language_COUNTRY
  GettextLocalize::default_methods = [:param, :session, :header]
end

before filter in controller

If you do not like the default (searching params/session/cookie/headers), here is how you can change it.

Possible locale finding methods are:

• param: GET or POST parameter named by default 'lang' or with the name specified
• cookie: cookie named by default 'lang'
• session: session variable named by default 'lang'
• header: HTTP user header named by default HTTP_ACCEPT_LANGUAGES, sent by the web browser

Examples

Tries to read the session from a param named 'locale',
then from a session['locale']
then from the header,
then falls back to fallback_locale

before_filter(:except=>"feed"){|c| c.set_locale_by [:param, :session, :header], 'locale' }

Sets the locale fixed but only in the controller.

before_filter{|c| c.set_default_locale 'ca_ES' }

Sets the country fixed in the controller.

before_filter{|c| c.set_default_country 'es' }

Sets the locale by cookie and if not by session.

before_filter :set_locale_by_session
before_filter :set_locale_by_cookie

Detection priorities

locale

• locale set in controller with set_locale(lang)
• locale set in environment.rb with GettextLocalize::default_locale = lang
• locale set in environment.rb variable $LANG
• locale set in this plugin init.rb with GettextLocalize::fallback_locale = lang

country

• country set in controller with set_country(country)
• country part of locale
• country set in environment.rb with GettextLocalize::default_country = country
• country set in this plugins init.rb with GettextLocalize::fallback_country = country

textdomain

only important for enterprise-size website
An application can have serveral textdomains (e.g. Users/Accounting/HR...) that have different translations, so that a translator does not have to work through all translations, when only the Accounting department needs an update.

• textdomain set in plugin using plugin_bindtextdomain(textdomain), uses loadpath RAILS_ROOT/vendor/plugins/gettext_localize/locale
• textdomain set in controller with init_gettext(textdomain), uses loadpath RAILS_ROOT/locale
• textdomain set in environment.rb with GettextLocalize::default_textdomain = textdomain
• app_name set in environment.rb with GettextLocalize::app_name = app_name
• name of the directory the rails app is in

Times and Dates

The classes Time, Date and DateTime are overwritten to localize to_s and strftime

strftime

The formats are localized using gettext, so to add a locale you only need to translate po/gettext_localize.pot

The following formats are overwritten:

• %A full day of the week
• %a abbreviated day of the week
• %B full name of the month
• %b abbreviated name of the month

The following formats are added:

• %V day of the month and monthname, like '11 of September'
• %v day of the month with zeros and monthname, like '04 of July'

The %V format is added because there are languages that vary the structure depending of the monthname, for example in Catalan you say "5 de Desembre" and "11 d'Abril".

to_s

Rails adds standart to_s formats. You can say Time.now.to_s(:db) or 1.week.ago.to_s(:short). These formats are also translated using gettext. We suppose :db and :rfc822 are not translatable since they are used for data saving.

ActiveRecord is overwritten to save Dates using strftime("%Y-%m-%d") and not to_s wich can be localized and would crash.

Helpers

The countries.yml file defines per country currency and date order options.

To set the year-month-day order depending on the locale:

• DateHelper::date_select
• DateHelper::select_date
• DateHelper::datetime_select
• DateHelper::select_datetime
• InstanceTag::to_datetime_select_tag

To set the currency depending on the country NumberHelper::number_to_currency
To set the connector depending on the locale Array::to_sentence

Acknowledgments

Authors: Ramon Salvadó, Miquel Ibero, Pau Colomer

RubyForge Project Page

Any questions/comments can be addressed to Ramon Salvadó

• Jester for Localization simplified plugin from which we borrowed some code/concepts.
• Masao Mutoh for ruby-gettext.