diff options
Diffstat (limited to 'railties/guides/source/i18n.textile')
| -rw-r--r-- | railties/guides/source/i18n.textile | 46 |
1 files changed, 26 insertions, 20 deletions
diff --git a/railties/guides/source/i18n.textile b/railties/guides/source/i18n.textile index 8a39bdf3c1..ac05e1c6c7 100644 --- a/railties/guides/source/i18n.textile +++ b/railties/guides/source/i18n.textile @@ -1,4 +1,4 @@ -h2. Rails Internationalization (I18n) API +lh2. Rails Internationalization (I18n) API The Ruby I18n (shorthand for _internationalization_) gem which is shipped with Ruby on Rails (starting from Rails 2.2) provides an easy-to-use and extensible framework for *translating your application to a single custom language* other than English or for *providing multi-language support* in your application. @@ -10,7 +10,7 @@ So, in the process of _internationalizing_ your Rails application you have to: * Tell Rails where to find locale dictionaries * Tell Rails how to set, preserve and switch locale -In the process of _localizing_ your application you'll probably want to do following three things: +In the process of _localizing_ your application you'll probably want to do the following three things: * Replace or supplement Rails' default locale -- e.g. date and time formats, month names, Active Record model names, etc * Abstract strings in your application into keyed dictionaries -- e.g. flash messages, static text in your views, etc. @@ -305,12 +305,12 @@ end # app/controllers/home_controller.rb class HomeController < ApplicationController def index - flash[:notice] = "Hello flash!" + flash[:notice] = "Hello Flash" end end # app/views/home/index.html.erb -<h1>Hello world!</h1> +<h1>Hello World</h1> <p><%= flash[:notice] %></p> </ruby> @@ -344,8 +344,8 @@ So let's add the missing translations into the dictionary files (i.e. do the "lo <ruby> # config/locales/en.yml en: - hello_world: Hello World - hello_flash: Hello Flash + hello_world: Hello world! + hello_flash: Hello flash! # config/locales/pirate.yml pirate: @@ -586,7 +586,7 @@ I18n.t :foo I18n.l Time.now </ruby> -Explicitely passing a locale: +Explicitly passing a locale: <ruby> I18n.t :foo, :locale => :de @@ -623,7 +623,7 @@ pt: bar: baz </ruby> -As you see, in both cases the toplevel key is the locale. +:foo+ is a namespace key and +:bar+ is the key for the translation "baz". +As you see, in both cases the top level key is the locale. +:foo+ is a namespace key and +:bar+ is the key for the translation "baz". Here is a "real" example from the Active Support +en.yml+ translations YAML file: @@ -649,7 +649,7 @@ Generally we recommend using YAML as a format for storing translations. There ar 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. +You can use the methods +Model.model_name.human+ and +Model.human_attribute_name(attribute)+ to transparently look up translations for your model and attribute names. For example when you add the following translations: @@ -664,7 +664,7 @@ en: # will translate User attribute "login" as "Handle" </ruby> -Then +User.human_name+ will return "Dude" and +User.human_attribute_name("login")+ will return "Handle". +Then +User.model_name.human+ will return "Dude" and +User.human_attribute_name("login")+ will return "Handle". h5. Error Message Scopes @@ -713,12 +713,12 @@ end Then Active Record will look for messages in this order: <ruby> -activerecord.errors.models.admin.attributes.title.blank +activerecord.errors.models.admin.attributes.name.blank activerecord.errors.models.admin.blank -activerecord.errors.models.user.attributes.title.blank +activerecord.errors.models.user.attributes.name.blank activerecord.errors.models.user.blank activerecord.errors.messages.blank -errors.attributes.title.blank +errors.attributes.name.blank errors.messages.blank </ruby> @@ -780,15 +780,15 @@ 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. -* +datetime_select+ and +select_month+ use translated month names for populating the resulting select tag. See "date.month_names":http://github.com/rails/rails/blob/master/activesupport/lib/active_support/locale/en.yml#L15 for translations. +datetime_select+ also looks up the order option from "date.order":http://github.com/rails/rails/blob/master/activesupport/lib/active_support/locale/en.yml#L18 (unless you pass the option explicitely). All date selection helpers translate the prompt using the translations in the "datetime.prompts":http://github.com/rails/rails/blob/master/actionpack/lib/action_view/locale/en.yml#L83 scope if applicable. +* +datetime_select+ and +select_month+ use translated month names for populating the resulting select tag. See "date.month_names":http://github.com/rails/rails/blob/master/activesupport/lib/active_support/locale/en.yml#L15 for translations. +datetime_select+ also looks up the order option from "date.order":http://github.com/rails/rails/blob/master/activesupport/lib/active_support/locale/en.yml#L18 (unless you pass the option explicitly). All date selection helpers translate the prompt using the translations in the "datetime.prompts":http://github.com/rails/rails/blob/master/actionpack/lib/action_view/locale/en.yml#L83 scope if applicable. * 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 -* +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#L29 scope. They also support translations for inherited class names (e.g. for use with STI) as explained above in "Error message scopes". +* +model_name.human+ 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#L29 scope. They also support translations for inherited class names (e.g. for use with STI) as explained above in "Error message scopes". -* +ActiveRecord::Errors#generate_message+ (which is used by Active Record validations but may also be used manually) uses +human_name+ and +human_attribute_name+ (see above). It also translates the error message and supports translations for inherited class names as explained above in "Error message scopes". +* +ActiveRecord::Errors#generate_message+ (which is used by Active Record validations but may also be used manually) uses +model_name.human+ and +human_attribute_name+ (see above). It also translates the error message and supports translations for inherited class names as explained above in "Error message scopes". *+ 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 +' '+). @@ -809,6 +809,12 @@ That does not mean you're stuck with these limitations, though. The Ruby I18n ge I18n.backend = Globalize::Backend::Static.new </ruby> +You can also use the Chain backend to chain multiple backends together. This is useful when you want to use standard translations with a Simple backend but store custom application translations in a database or other backends. For example, you could use the ActiveRecord backend and fall back to the (default) Simple backend: + +<ruby> +I18n.backend = I18n::Backend::Chain.new(I18n::Backend::ActiveRecord.new, I18n.backend) +</ruby> + h4. Using Different Exception Handlers The I18n API defines the following exceptions that will be raised by backends when the corresponding unexpected conditions occur: @@ -852,7 +858,7 @@ h3. Conclusion 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. +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 "mailing list":http://groups.google.com/group/rails-i18n. h3. Contributing to Rails I18n @@ -867,10 +873,10 @@ If you find your own locale (language) missing from our "example translations da h3. Resources * "rails-i18n.org":http://rails-i18n.org - Homepage of the rails-i18n project. You can find lots of useful resources on the "wiki":http://rails-i18n.org/wiki. -* "rails-i18n Google group":http://groups.google.com/group/rails-i18n - The project's mailing list. +* "Google group: rails-i18n":http://groups.google.com/group/rails-i18n - The project's mailing list. * "Github: rails-i18n":http://github.com/svenfuchs/rails-i18n/tree/master - Code repository for the rails-i18n project. Most importantly you can find lots of "example translations":http://github.com/svenfuchs/rails-i18n/tree/master/rails/locale for Rails that should work for your application in most cases. -* "Lighthouse: rails-i18n":http://i18n.lighthouseapp.com/projects/14948-rails-i18n/overview - Issue tracker for the rails-i18n project. * "Github: i18n":http://github.com/svenfuchs/i18n/tree/master - Code repository for the i18n gem. +* "Lighthouse: rails-i18n":http://i18n.lighthouseapp.com/projects/14948-rails-i18n/overview - Issue tracker for the rails-i18n project. * "Lighthouse: i18n":http://i18n.lighthouseapp.com/projects/14947-ruby-i18n/overview - Issue tracker for the i18n gem. @@ -879,7 +885,7 @@ h3. Authors * "Sven Fuchs":http://www.workingwithrails.com/person/9963-sven-fuchs (initial author) * "Karel Minařík":http://www.workingwithrails.com/person/7476-karel-mina-k -If you found this guide useful please consider recommending its authors on "workingwithrails":http://www.workingwithrails.com. +If you found this guide useful, please consider recommending its authors on "workingwithrails":http://www.workingwithrails.com. h3. Footnotes |