diff options
author | Xavier Noria <fxn@hashref.com> | 2009-03-14 22:37:33 +0100 |
---|---|---|
committer | Xavier Noria <fxn@hashref.com> | 2009-03-14 22:44:38 +0100 |
commit | b7244276414999602cf99c7e9f30b8208d6ed158 (patch) | |
tree | 2099a85070cff46765aca2a50a07f72a70ff7198 /railties/guides/source | |
parent | 4216213f0610bddbb9f283fc5a2dfbfa9be75509 (diff) | |
download | rails-b7244276414999602cf99c7e9f30b8208d6ed158.tar.gz rails-b7244276414999602cf99c7e9f30b8208d6ed158.tar.bz2 rails-b7244276414999602cf99c7e9f30b8208d6ed158.zip |
revised titles in i18n guide
Diffstat (limited to 'railties/guides/source')
-rw-r--r-- | railties/guides/source/i18n.textile | 70 |
1 files changed, 35 insertions, 35 deletions
diff --git a/railties/guides/source/i18n.textile b/railties/guides/source/i18n.textile index c369ce9a7d..f9c2b87d72 100644 --- a/railties/guides/source/i18n.textile +++ b/railties/guides/source/i18n.textile @@ -22,7 +22,7 @@ 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. -h3. How I18n in Ruby on Rails works +h3. How I18n in Ruby on Rails Works Internationalization is a complex problem. Natural languages differ in so many ways (e.g. in pluralization rules) that it is hard to provide tools for solving all problems at once. For that reason the Rails I18n API focuses on: @@ -31,7 +31,7 @@ Internationalization is a complex problem. Natural languages differ in so many w As part of this solution, *every static string in the Rails framework* -- e.g. Active Record validation messages, time and date formats -- *has been internationalized*, so _localization_ of a Rails application means "over-riding" these defaults. -h4. The overall architecture of the library +h4. The Overall Architecture of the Library Thus, the Ruby I18n gem is split into two parts: @@ -42,7 +42,7 @@ As a user you should always only access the public methods on the I18n module, b NOTE: It is possible (or even desirable) to swap the shipped Simple backend with a more powerful one, which would store translation data in a relational database, GetText dictionary, or similar. See section "Using different backends":#usingdifferentbackends below. -h4. The public I18n API +h4. The Public I18n API The most important methods of the I18n API are: @@ -70,11 +70,11 @@ backend # Use a different backend So, let's internationalize a simple Rails application from the ground up in the next chapters! -h3. Setup the Rails application for internationalization +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. -h4. Configure the I18n module +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. @@ -107,7 +107,7 @@ The default +environment.rb+ files has instruction how to add locales from anoth # config.i18n.default_locale = :de </ruby> -h4. Optional: custom I18n configuration setup +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. @@ -123,7 +123,7 @@ I18n.load_path << Dir[ File.join(RAILS_ROOT, 'lib', 'locale', '*.{rb,yml}') ] I18n.default_locale = :pt </ruby> -h4. Setting and passing the locale +h4. Setting and Passing the Locale If you want to translate your Rails application to a *single language other than English* (the default locale), you can set I18n.default_locale to your locale in +environment.rb+ or an initializer as shown above, and it will persist through the requests. @@ -180,7 +180,7 @@ class ApplicationController < ActionController::Base end </ruby> -h4. Setting the locale from the domain name +h4. Setting the Locale from the Domain Name One option you have is to set the locale from the domain name where your application runs. For example, we want +www.example.com+ to load the English (or default) locale, and +www.example.es+ to load the Spanish locale. Thus the _top-level domain name_ is used for locale setting. This has several advantages: @@ -231,7 +231,7 @@ assuming you would set +APP_CONFIG[:deutsch_website_url]+ to some value like +ht This solution has aforementioned advantages, however, you may not be able or may not want to provide different localizations ("language versions") on different domains. The most obvious solution would be to include locale code in the URL params (or request path). -h4. Setting the locale from the URL params +h4. Setting the Locale from the URL Params The most usual way of setting (and passing) the locale would be to include it in URL params, as we did in the +I18n.locale = params[:locale]+ _before_filter_ in the first example. We would like to have URLs like +www.example.com/books?locale=ja+ or +www.example.com/ja/books+ in this case. @@ -277,12 +277,12 @@ Do take special care about the *order of your routes*, so this route declaration IMPORTANT: This solution has currently one rather big *downside*. Due to the _default_url_options_ implementation, you have to pass the +:id+ option explicitely, like this: +link_to 'Show', book_url(:id => book)+ and not depend on Rails' magic in code like +link_to 'Show', book+. If this should be a problem, have a look at two plugins which simplify work with routes in this way: Sven Fuchs's "routing_filter":http://github.com/svenfuchs/routing-filter/tree/master and Raul Murciano's "translate_routes":http://github.com/raul/translate_routes/tree/master. See also the page "How to encode the current locale in the URL":http://rails-i18n.org/wiki/pages/how-to-encode-the-current-locale-in-the-url in the Rails i18n Wiki. -h4. Setting the locale from the client supplied information +h4. Setting the Locale from the Client Supplied Information In specific cases, it would make sense to set the locale from client-supplied information, i.e. not from the URL. This information may come for example from the users' prefered language (set in their browser), can be based on the users' geographical location inferred from their IP, or users can provide it simply by choosing the locale in your application interface and saving it to their profile. This approach is more suitable for web-based applications or services, not for websites -- see the box about _sessions_, _cookies_ and RESTful architecture above. -h5. Using Accept-Language +h5. Using +Accept-Language+ One source of client supplied information would be an +Accept-Language+ HTTP header. People may "set this in their browser":http://www.w3.org/International/questions/qa-lang-priorities or other clients (such as _curl_). @@ -302,15 +302,15 @@ end 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. -h5. Using GeoIP (or similar) database +h5. Using GeoIP (or Similar) Database Another way of choosing the locale from client information would be to use a database for mapping the client IP to the region, such as "GeoIP Lite Country":http://www.maxmind.com/app/geolitecountry. The mechanics of the code would be very similar to the code above -- you would need to query the database for the user's IP, and look up your prefered locale for the country/region/city returned. -h5. User profile +h5. User Profile You can also provide users of your application with means to set (and possibly over-ride) the locale in your application interface, as well. Again, mechanics for this approach would be very similar to the code above -- you'd probably let users choose a locale from a dropdown list and save it to their profile in the database. Then you'd set the locale to this value. -h3. Internationalizing your application +h3. Internationalizing your Application OK! Now you've initialized I18n support for your Ruby on Rails application and told it which locale to use and how to preserve it between requests. With that in place, you're now ready for the really interesting stuff. @@ -387,7 +387,7 @@ NOTE: You need to restart the server when you add new locale files. You may use YAML (+.yml+) or plain Ruby (+.rb+) files for storing your translations in SimpleStore. YAML is the prefered option among Rails developers. However, it has one big disadvantage. YAML is very sensitive to whitespace and special characters, so the application may not load your dictionary properly. Ruby files will crash your application on first request, so you may easily find what's wrong. (If you encounter any "weird issues" with YAML dictionaries, try putting the relevant portion of your dictionary into a Ruby file.) -h4. Adding Date/Time formats +h4. Adding Date/Time Formats OK! Now let's add a timestamp to the view, so we can demo the *date/time localization* feature as well. To localize the time format you pass the Time object to +I18n.l+ or (preferably) use Rails' +#l+ helper. You can pick a format by passing the +:format+ option -- by default the +:default+ format is used. @@ -414,13 +414,13 @@ So that would give you: TIP: Right now you might need to add some more date/time formats in order to make the I18n backend work as expected (at least for the 'pirate' locale). Of course, there's a great chance that somebody already did all the work by *translating Rails's defaults for your locale*. See the "rails-i18n repository at Github":http://github.com/svenfuchs/rails-i18n/tree/master/rails/locale for an archive of various locale files. When you put such file(s) in +config/locale/+ directory, they will automatically be ready for use. -h4. Localized views +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.) 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. -h4. Organization of locale files +h4. Organization of Locale Files When you are using the default SimpleStore shipped with the i18n library, dictionaries are stored in plain-text files on the disc. Putting translations for all parts of your application in one file per locale could be hard to manage. You can store these files in a hierarchy which makes sense to you. @@ -460,7 +460,7 @@ NOTE: The default locale loading mechanism in Rails does not load locale files i Do check the "Rails i18n Wiki":http://rails-i18n.org/wiki for list of tools available for managing translations. -h3. Overview of the I18n API features +h3. Overview of the I18n API Features You should have good understanding of using the i18n library now, knowing all neccessary aspects of internationalizing a basic Rails application. In the following chapters, we'll cover it's features in more depth. @@ -471,9 +471,9 @@ Covered are features like these: * pluralizing translations * localizing dates, numbers, currency, etc. -h4. Looking up translations +h4. Looking up Translations -h5. Basic lookup, scopes and nested keys +h5. Basic Lookup, Scopes and Nested Keys Translations are looked up by keys which can be both Symbols or Strings, so these calls are equivalent: @@ -523,7 +523,7 @@ I18n.t :missing, :default => [:also_missing, 'Not here'] # => 'Not here' </ruby> -h5. Bulk and namespace lookup +h5. Bulk and Namespace Lookup To look up multiple translations at once, an array of keys can be passed: @@ -539,7 +539,7 @@ I18n.t 'activerecord.errors.messages' # => { :inclusion => "is not included in the list", :exclusion => ... } </ruby> -h5. "Lazy" lookup +h5. "Lazy" Lookup Rails 2.3 implements a convenient way to look up the locale inside _views_. When you have the following dictionary: @@ -595,7 +595,7 @@ I.e. the translation denoted as +:one+ is regarded as singular, the other is use If the lookup for the key does not return a Hash suitable for pluralization, an +18n::InvalidPluralizationData+ exception is raised. -h4. Setting and passing a locale +h4. Setting and Passing a Locale The locale can be either set pseudo-globally to +I18n.locale+ (which uses +Thread.current+ like, e.g., +Time.zone+) or can be passed as an option to +#translate+ and +#localize+. @@ -620,7 +620,7 @@ I18n.l Time.now, :locale => :de I18n.default_locale = :de </ruby> -h3. How to store your custom translations +h3. How to Store your Custom Translations The Simple backend shipped with Active Support allows you to store translations in both plain Ruby and YAML format. [2] @@ -668,7 +668,7 @@ I18n.t :short, :scope => [:date, :formats] Generally we recommend using YAML as a format for storing translations. There are cases, though, where you want to store Ruby lambdas as part of your locale data, e.g. for special date formats. -h4. Translations for Active Record models +h4. Translations for Active Record Models You can use the methods +Model.human_name+ and +Model.human_attribute_name(attribute)+ to transparently look up translations for your model and attribute names. @@ -687,7 +687,7 @@ en: Then +User.human_name+ will return "Dude" and +User.human_attribute_name(:login)+ will return "Handle". -h5. Error message scopes +h5. Error Message Scopes Active Record validation error messages can also be translated easily. Active Record gives you a couple of namespaces where you can place your message translations in order to provide different messages and translation for certain models, attributes, and/or validations. It also transparently takes single table inheritance into account. @@ -739,7 +739,7 @@ activerecord.errors.messages.blank This way you can provide special translations for various error messages at different points in your models inheritance chain and in the attributes, models, or default scopes. -h5. Error message interpolation +h5. Error Message Interpolation The translated model name, translated attribute name, and value are always available for interpolation. @@ -770,7 +770,7 @@ So, for example, instead of the default error message +"can not be blank"+ you c | validates_numericality_of | :odd | :odd | -| | validates_numericality_of | :even | :even | -| -h5. Translations for the Active Record error_messages_for helper +h5. Translations for the Active Record +error_messages_for+ Helper If you are using the Active Record +error_messages_for+ helper, you will want to add translations for it. @@ -787,11 +787,11 @@ en: body: "There were problems with the following fields:" </yaml> -h4. Overview of other built-in methods that provide I18n support +h4. Overview of Other Built-In Methods that Provide I18n Support Rails uses fixed strings and other localizations, such as format strings and other format information in a couple of helpers. Here's a brief overview. -h5. Action View helper methods +h5. Action View Helper Methods * +distance_of_time_in_words+ translates and pluralizes its result and interpolates the number of seconds, minutes, hours, and so on. See "datetime.distance_in_words":http://github.com/rails/rails/blob/master/actionpack/lib/action_view/locale/en.yml#L51 translations. @@ -799,7 +799,7 @@ h5. Action View helper methods * The +number_to_currency+, +number_with_precision+, +number_to_percentage+, +number_with_delimiter+, and +number_to_human_size+ helpers use the number format settings located in the "number":http://github.com/rails/rails/blob/master/actionpack/lib/action_view/locale/en.yml#L2 scope. -h5. Active Record methods +h5. Active Record Methods * +human_name+ and +human_attribute_name+ use translations for model names and attribute names if available in the "activerecord.models":http://github.com/rails/rails/blob/master/activerecord/lib/active_record/locale/en.yml#L43 scope. They also support translations for inherited class names (e.g. for use with STI) as explained above in "Error message scopes". @@ -807,14 +807,14 @@ h5. Active Record methods *+ ActiveRecord::Errors#full_messages+ prepends the attribute name to the error message using a separator that will be looked up from "activerecord.errors.format.separator":http://github.com/rails/rails/blob/master/actionpack/lib/action_view/locale/en.yml#L91 (and which defaults to +' '+). -h5. Active Support methods +h5. Active Support Methods * +Array#to_sentence+ uses format settings as given in the "support.array":http://github.com/rails/rails/blob/master/activesupport/lib/active_support/locale/en.yml#L30 scope. -h3. Customize your I18n setup +h3. Customize your I18n Setup -h4. Using different backends +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. @@ -824,7 +824,7 @@ That does not mean you're stuck with these limitations, though. The Ruby I18n ge I18n.backend = Globalize::Backend::Static.new </ruby> -h4. Using different exception handlers +h4. Using Different Exception Handlers The I18n API defines the following exceptions that will be raised by backends when the corresponding unexpected conditions occur: |