i18n_gettext

i18n_gettext copied to clipboard

= I18nGettext

Update 2009-06-27: Before strugling with the old Gettext ruby libraries, you might want to try out the fast_gettext plugin for rails http://github.com/grosser/gettext_i18n_rails by Michael Grosser which already provides the functionality provided by this plugin with its own, faster, and frankly better written and designed backend.

== Introduction

Gettext support for your Rails 2.2 or newer applications using the Rails I18n framework, using the Gettext gem from Masao Mutoh (http://rubyforge.org/projects/gettext/).

Provides a few simple wrapper methods to the I18n methods using the Gettext syntax thus permitting the automatic extraction of strings for translation.

The Gettext backend extends the Simple backend provided by Rails and sends translation requests not recognised to Gettext which in turn will extract messages from the standard .mo translation dictionaries. This means that the example translation files provided by the Rails i18n team http://rails-i18n.org can be used for all the base Rails methods such as +distance_in_words+ and +Date+ formatting. To this end, if the gettext methods are not used to translate, the Gettext dictionaries will not be used allowing the default I18n process to take effect, for example:

_('Some text') = "Some text" I18n.t 'Some text' = "translation missing: Some text"

Plural strings are supported using the powerful Gettext syntax.

This plugin should act as a drop-in replacement for the old gettext/rails extension, but some minor changes are required. The +after_init_gettext+ methods for example are no longer supported, but can be replaced with a simple +before_filter+ call.

== Authors

Project initiated at Rails-Hackathon http://rails-hackathon.org in Madrid, February 2009, by:

• Sam Lown (http://www.samlown.com)
• Fernando Blat (http://www.inwebwetrust.net)

Thanks must go out to the Rails i18n development team (http://rails-i18n.org) for their excellent patch included in Rails 2.2. It really did make our plugin almost trivial to implement.

== Install

We're assuming in these examples that your Rails application has either been created or upgraded to Rails 2.2 or higher.

1. Install the plugin in your application:

./script/plugin install git://github.com/ferblape/i18n_gettext.git

2. Add the gettext library to your environment and ensure any old usage of Gettext/rails is removed. Something similar to the following should be added to your Rails Initializer config:

config.gem "gettext", :version => '1.93.0', :lib => 'gettext'

3. (Optional) Add support for the Gettext backend by including the following in your config/environment.rb file after Initialization:

I18n.backend = I18n::Backend::GetTextWrapper.new I18n.backend.default_domain = 'somedomain'

The default domain is used by Gettext to describe which .po files should be used for the translations. This used to be defined using the +init_gettext+ method. See the Gettext manuals for more information.

4. Ensure that any old gettext calls have been removed or replaced, such as +init_gettext+, +after_init_gettext+, or +set_locale+. The standard Rails +before_filter+ method and new +I18n.locale=+ may be useful for this.

TODO describe how to setup the .po, .mo, and message reaper methods using Gettext, but it should be pretty much the same as with the old Gettext extension.

== Using Domains

Gettext has a great feature which allows you to devide your applications into sections or "domains" so that you have different sets of translations for different parts of your application. This can be used for example to have a translations for a generic or re-used administration area seperate from those of the frontend.

In the old Gettext Rails extension, this was supported using the +init_gettext+ method, now however, the following can be set for the same effect:

I18n.backend.default_domain = 'administration'

Include this in a section of your shared application controller for effect.

== Possible Issues

We're not sure how this will perform using Rails in Multi-threaded mode as it depends greatly on the way Gettext works. You can probably rest well assured though that it will not work as expected. Gettext has a tendancy to use lots of globals, including the +Locale+ singleton class which has not been developed for multi-threading to the best of our knowledge.

== Guarantee

We do not guarantee that this plugin will support all of your gettext requirements, nor that it will work correctly with your applications. Nonetheless, we hope it does, and feel free to contact either Fernando or myself with your issues.

Copyright (c) 2009 [Sam Lown, Fernando Blat], released under the MIT license