Gettext Localize

Authors:

Ramon Salvadó <rsalvado@gnuine.com>, Miquel Ibero , Pau Colomer

Any questions/comments can be addressed to Ramon Salvadó <rsalvado@gnuine.com>

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 has been tested with the following languages: catalan, spanish, english.

Installation

Needs to have the gettext gem installed:

sudo gem install gettext

To install the plugin:

script/plugin install svn://rubyforge.org/var/svn/gettextlocalize/trunk/gettext_localize

Features

works with rails 1.2 and loads the correct ruby-gettext
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

Configuration

install gettext: gem install gettext
localize your app texts adding the gettext function _("translate this")
generate the application pot files: rake gettext:updatepo creates a po/app.pot
translate the messages creating a directory for every language: po/lang1/app.po
generate the mo files : rake gettext:makemo
define the default language (by default takes your $LANG environment variable) in your environment.rb

Needed things

ruby gettext: gem install gettext

Priorities

locale:

locale set in controller with set_locale(lang)
locale set in environment with GettextLocalize::default_locale = lang
locale set in environment 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 with GettextLocalize::default_country = country
country set in this plugins init.rb with GettextLocalize::fallback_country = country

textdomain:

textdomain set in plugin using plugin_bindtextdomain(textdomain), uses loadpath RAILS_ROOT/vendor/plugins/$plugin/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 of the directory the rails app is in

Before filters in controller

Possible locale find methods are:

param: looks for a GET or POST parameter named by default ‘lang’ or with the name specified
cookie: looks for a cookie named by default ‘lang‘
session: looks for a session variable named by default ‘lang‘
header: looks for a HTTP user header named by default HTTP_ACCEPT_LANGUAGES, sent by the web browser

Don‘t put set_locale(lang) directly in the controller, because it will set the locale in all the aplication, use always before_filter.

Sample Configuration in environment.rb

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

Samples of controller filters

Tries to read the session from a param named ‘locale’, then from a session var named ‘locale’ and the 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

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 standard way

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 YAML 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:

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

README