diff options
author | Mike Gunderloy <MikeG1@larkfarm.com> | 2009-03-14 17:04:10 -0500 |
---|---|---|
committer | Mike Gunderloy <MikeG1@larkfarm.com> | 2009-03-14 17:04:41 -0500 |
commit | 9ac0dade6d788bfed8338941dc4f29c19d4923af (patch) | |
tree | b22ee36ffb8c9fb4c9cd82825a3730067c9d9010 /railties/guides | |
parent | 1bd5a64f5ad30b0b8b018c52ba3d002c338b3c57 (diff) | |
download | rails-9ac0dade6d788bfed8338941dc4f29c19d4923af.tar.gz rails-9ac0dade6d788bfed8338941dc4f29c19d4923af.tar.bz2 rails-9ac0dade6d788bfed8338941dc4f29c19d4923af.zip |
Minor edits to I18n guide; publish guide
Diffstat (limited to 'railties/guides')
-rw-r--r-- | railties/guides/source/i18n.textile | 41 | ||||
-rw-r--r-- | railties/guides/source/index.erb.textile | 2 |
2 files changed, 22 insertions, 21 deletions
diff --git a/railties/guides/source/i18n.textile b/railties/guides/source/i18n.textile index f9c2b87d72..0b5f872a72 100644 --- a/railties/guides/source/i18n.textile +++ b/railties/guides/source/i18n.textile @@ -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 @@ -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. @@ -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. @@ -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> @@ -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 @@ -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. @@ -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 @@ -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] @@ -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: @@ -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 @@ -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: @@ -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. @@ -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. diff --git a/railties/guides/source/index.erb.textile b/railties/guides/source/index.erb.textile index f0b666432d..4c8dd65a04 100644 --- a/railties/guides/source/index.erb.textile +++ b/railties/guides/source/index.erb.textile @@ -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 %> |