Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Minor edits to I18n guide; publish guide
  • Loading branch information
Mike Gunderloy authored and Mike Gunderloy committed Mar 14, 2009
1 parent 1bd5a64 commit 9ac0dad
Show file tree
Hide file tree
Showing 2 changed files with 22 additions and 21 deletions.
41 changes: 21 additions & 20 deletions railties/guides/source/i18n.textile
Expand Up @@ -13,14 +13,14 @@ So, in the process of _internationalizing_ your Rails application you have to:
In the process of _localizing_ your application you'll probably want to do following three things:

* Replace or supplement Rails' default locale -- e.g. date and time formats, month names, Active Record model names, etc
* Abstract texts in your application into keyed dictionaries -- e.g. flash messages, static texts in your views, etc
* Abstract strings in your application into keyed dictionaries -- e.g. flash messages, static text in your views, etc.
* Store the resulting dictionaries somewhere

This guide will walk you through the I18n API and contains a tutorial how to internationalize a Rails application from the start.

endprologue.

NOTE: The Ruby I18n framework provides you with all neccessary means for internationalization/localization of your Rails application. You may, however, use any of various plugins and extensions available, which add additional functionality or features. See Rails "I18n Wiki":http://rails-i18n.org/wiki for more information.
NOTE: The Ruby I18n framework provides you with all necessary means for internationalization/localization of your Rails application. You may, however, use any of various plugins and extensions available, which add additional functionality or features. See the Rails "I18n Wiki":http://rails-i18n.org/wiki for more information.

h3. How I18n in Ruby on Rails Works

Expand All @@ -35,7 +35,7 @@ h4. The Overall Architecture of the Library

Thus, the Ruby I18n gem is split into two parts:

* The public API of the i18n framework -- a Ruby module with public methods and definitions how the library works
* The public API of the i18n framework -- a Ruby module with public methods that define how the library works
* A default backend (which is intentionally named _Simple_ backend) that implements these methods

As a user you should always only access the public methods on the I18n module, but it is useful to know about the capabilities of the backend.
Expand Down Expand Up @@ -72,22 +72,22 @@ So, let's internationalize a simple Rails application from the ground up in the

h3. Setup the Rails Application for Internationalization

There are just a few, simple steps to get up and running with I18n support for your application.
There are just a few simple steps to get up and running with I18n support for your application.

h4. Configure the I18n Module

Following the _convention over configuration_ philosophy, Rails will set-up your application with reasonable defaults. If you need different settings, you can overwrite them easily.
Following the _convention over configuration_ philosophy, Rails will set up your application with reasonable defaults. If you need different settings, you can overwrite them easily.

Rails adds all +.rb+ and +.yml+ files from +config/locales+ directory to your *translations load path*, automatically.
Rails adds all +.rb+ and +.yml+ files from the +config/locales+ directory to your *translations load path*, automatically.

See the default +en.yml+ locale in this directory, containing a sample pair of translation strings:
The default +en.yml+ locale in this directory contains a sample pair of translation strings:

<ruby>
en:
hello: "Hello world"
</ruby>

This means, that in the +:en+ locale, the key _hello_ will map to _Hello world_ string. Every string inside Rails is internationalized in this way, see for instance Active Record validation messages in the "+activerecord/lib/active_record/locale/en.yml+":http://github.com/rails/rails/blob/master/activerecord/lib/active_record/locale/en.yml file or time and date formats in the "+activesupport/lib/active_support/locale/en.yml+":http://github.com/rails/rails/blob/master/activesupport/lib/active_support/locale/en.yml file. You can use YAML or standard Ruby Hashes to store translations in the default (Simple) backend.
This means, that in the +:en+ locale, the key _hello_ will map to the _Hello world_ string. Every string inside Rails is internationalized in this way, see for instance Active Record validation messages in the "+activerecord/lib/active_record/locale/en.yml+":http://github.com/rails/rails/blob/master/activerecord/lib/active_record/locale/en.yml file or time and date formats in the "+activesupport/lib/active_support/locale/en.yml+":http://github.com/rails/rails/blob/master/activesupport/lib/active_support/locale/en.yml file. You can use YAML or standard Ruby Hashes to store translations in the default (Simple) backend.

The I18n library will use *English* as a *default locale*, i.e. if you don't set a different locale, +:en+ will be used for looking up translations.

Expand All @@ -111,15 +111,16 @@ h4. Optional: Custom I18n Configuration Setup

For the sake of completeness, let's mention that if you do not want to use the +environment.rb+ file for some reason, you can always wire up things manually, too.

To tell the I18n library where it can find your custom translation files you can specify the load path anywhere in your application - just make sure it gets run before any translations are actually looked up. You might also want to change the default locale. The simplest thing possible is to put the following into an *initializer*:
To tell the I18n library where it can find your custom translation files you can specify the load path anywhere in your application - just make sure it gets run before any translations are actually looked up. You might also want to change the default locale. The simplest thing possible is to put the following into an initializer:

<ruby>
# in config/initializer/locale.rb

# tell the I18n library where to find your translations
I18n.load_path << Dir[ File.join(RAILS_ROOT, 'lib', 'locale', '*.{rb,yml}') ]
I18n.load_path << Dir[ File.join(RAILS_ROOT, 'lib', 'locale',
'*.{rb,yml}') ]

# set default locale to something else then :en
# set default locale to something other than :en
I18n.default_locale = :pt
</ruby>

Expand Down Expand Up @@ -300,7 +301,7 @@ def extract_locale_from_accept_language_header
end
</ruby>

Of course, in a production environment you would need much more robust code, and could use a plugin such as Iaian Hecker's "http_accept_language":http://github.com/iain/http_accept_language or even Rack middleware such as Ryan Tomayko's "locale":http://github.com/rtomayko/rack-contrib/blob/master/lib/rack/locale.rb.
Of course, in a production environment you would need much more robust code, and could use a plugin such as Iain Hecker's "http_accept_language":http://github.com/iain/http_accept_language or even Rack middleware such as Ryan Tomayko's "locale":http://github.com/rtomayko/rack-contrib/blob/master/lib/rack/locale.rb.

h5. Using GeoIP (or Similar) Database

Expand Down Expand Up @@ -416,7 +417,7 @@ TIP: Right now you might need to add some more date/time formats in order to mak

h4. Localized Views

Rails 2.3 brings one convenient feature: localized views (templates). Let's say you have a _BooksController_ in your application. Your _index_ action renders content in +app/views/books/index.html.erb+ template. When you put a _localized variant_ of this template: *+index.es.html.erb+* in the same directory, Rails will render content in this template, when the locale is set to +:es+. When the locale is set to the default locale, the generic +index.html.erb+ view will be used. (Future Rails versions may well bring this _automagic_ localization to assets in +public+, etc.)
Rails 2.3 introduces another convenient localization feature: localized views (templates). Let's say you have a _BooksController_ in your application. Your _index_ action renders content in +app/views/books/index.html.erb+ template. When you put a _localized variant_ of this template: *+index.es.html.erb+* in the same directory, Rails will render content in this template, when the locale is set to +:es+. When the locale is set to the default locale, the generic +index.html.erb+ view will be used. (Future Rails versions may well bring this _automagic_ localization to assets in +public+, etc.)

You can make use of this feature, e.g. when working with a large amount of static content, which would be clumsy to put inside YAML or Ruby dictionaries. Bear in mind, though, that any change you would like to do later to the template must be propagated to all of them.

Expand Down Expand Up @@ -451,7 +452,7 @@ For example, your +config/locale+ directory could look like this:

This way, you can separate model and model attribute names from text inside views, and all of this from the "defaults" (e.g. date and time formats). Other stores for the i18n library could provide different means of such separation.

NOTE: The default locale loading mechanism in Rails does not load locale files in nested dictionaries, like we have here. So, for this to work, we must explicitely tell Rails to look further:
NOTE: The default locale loading mechanism in Rails does not load locale files in nested dictionaries, like we have here. So, for this to work, we must explicitly tell Rails to look further:

<ruby>
# config/environment.rb
Expand Down Expand Up @@ -482,7 +483,7 @@ I18n.t :message
I18n.t 'message'
</ruby>

+translate+ also takes a +:scope+ option which can contain one or more additional keys that will be used to specify a “namespace” or scope for a translation key:
The +translate+ method also takes a +:scope+ option which can contain one or more additional keys that will be used to specify a “namespace” or scope for a translation key:

<ruby>
I18n.t :invalid, :scope => [:activerecord, :errors, :messages]
Expand Down Expand Up @@ -572,7 +573,7 @@ If a translation uses +:default+ or +:scope+ as an interpolation variable, an I+

h4. Pluralization

In English there's only a singular and a plural form for a given string, e.g. "1 message" and "2 messages". Other languages ("Arabic":http://www.unicode.org/cldr/data/charts/supplemental/language_plural_rules.html#ar, "Japanese":http://www.unicode.org/cldr/data/charts/supplemental/language_plural_rules.html#ja, "Russian":http://www.unicode.org/cldr/data/charts/supplemental/language_plural_rules.html#ru and many more) have different grammars that have additional or less "plural forms":http://www.unicode.org/cldr/data/charts/supplemental/language_plural_rules.html. Thus, the I18n API provides a flexible pluralization feature.
In English there are only one singular and one plural form for a given string, e.g. "1 message" and "2 messages". Other languages ("Arabic":http://www.unicode.org/cldr/data/charts/supplemental/language_plural_rules.html#ar, "Japanese":http://www.unicode.org/cldr/data/charts/supplemental/language_plural_rules.html#ja, "Russian":http://www.unicode.org/cldr/data/charts/supplemental/language_plural_rules.html#ru and many more) have different grammars that have additional or fewer "plural forms":http://www.unicode.org/cldr/data/charts/supplemental/language_plural_rules.html. Thus, the I18n API provides a flexible pluralization feature.

The +:count+ interpolation variable has a special role in that it both is interpolated to the translation and used to pick a pluralization from the translations according to the pluralization rules defined by CLDR:

Expand Down Expand Up @@ -614,7 +615,7 @@ I18n.t :foo, :locale => :de
I18n.l Time.now, :locale => :de
</ruby>

+I18n.locale+ defaults to +I18n.default_locale+ which defaults to :+en+. The default locale can be set like this:
The +I18n.locale+ defaults to +I18n.default_locale+ which defaults to :+en+. The default locale can be set like this:

<ruby>
I18n.default_locale = :de
Expand Down Expand Up @@ -816,7 +817,7 @@ h3. Customize your I18n Setup

h4. Using Different Backends

For several reasons the Simple backend shipped with Active Support only does the "simplest thing that ever could work" _for Ruby on Rails_ [3] ... which means that it is only guaranteed to work for English and, as a side effect, languages that are very similar to English. Also, the simple backend is only capable of reading translations but can not dynamically store them to any format.
For several reasons the Simple backend shipped with Active Support only does the "simplest thing that could possibly work" _for Ruby on Rails_ [3] ... which means that it is only guaranteed to work for English and, as a side effect, languages that are very similar to English. Also, the simple backend is only capable of reading translations but can not dynamically store them to any format.

That does not mean you're stuck with these limitations, though. The Ruby I18n gem makes it very easy to exchange the Simple backend implementation with something else that fits better for your needs. E.g. you could exchange it with Globalize's Static backend:

Expand Down Expand Up @@ -865,7 +866,7 @@ I18n.t :foo, :raise => true # always re-raises exceptions from the backend

h3. Conclusion

At this point you hopefully have a good overview about how I18n support in Ruby on Rails works and are ready to start translating your project.
At this point you should have a good overview about how I18n support in Ruby on Rails works and are ready to start translating your project.

If you find anything missing or wrong in this guide please file a ticket on "our issue tracker":http://i18n.lighthouseapp.com/projects/14948-rails-i18n/overview. If you want to discuss certain portions or have questions please sign up to our "mailinglist":http://groups.google.com/group/rails-i18n.

Expand All @@ -874,7 +875,7 @@ h3. Contributing to Rails I18n

I18n support in Ruby on Rails was introduced in the release 2.2 and is still evolving. The project follows the good Ruby on Rails development tradition of evolving solutions in plugins and real applications first, and only then cherry-picking the best-of-bread of most widely useful features for inclusion in the core.

Thus we encourage everybody to experiment with new ideas and features in plugins or other libraries and make them available to the community. (Don't forget to announce your work on our "mailinglist":http://groups.google.com/group/rails-i18n!)
Thus we encourage everybody to experiment with new ideas and features in plugins or other libraries and make them available to the community. (Don't forget to announce your work on our "mailing list":http://groups.google.com/group/rails-i18n!)

If you find your own locale (language) missing from our "example translations data":http://github.com/svenfuchs/rails-i18n/tree/master/rails/locale repository for Ruby on Rails, please "_fork_":http://github.com/guides/fork-a-project-and-submit-your-modifications the repository, add your data and send a "pull request":http://github.com/guides/pull-requests.

Expand Down
2 changes: 1 addition & 1 deletion railties/guides/source/index.erb.textile
Expand Up @@ -77,7 +77,7 @@ h3. Digging Deeper
This guide covers Rails integration with Rack and interfacing with other Rack components.
<% end %>

<% guide("Rails Internationalization API", 'i18n.html', :ticket => 23) do %>
<% guide("Rails Internationalization API", 'i18n.html') do %>
This guide covers how to add internationalization to your applications. Your application will be able to translate content to different languages, change pluralization rules, use correct date formats for each country and so on.
<% end %>

Expand Down

0 comments on commit 9ac0dad

Please sign in to comment.