diff options
author | Sven Fuchs <svenfuchs@artweb-design.de> | 2008-12-16 16:31:15 +0100 |
---|---|---|
committer | Sven Fuchs <svenfuchs@artweb-design.de> | 2008-12-16 16:31:15 +0100 |
commit | 44a831940dfab557a525b6a5b132238b53ce9a38 (patch) | |
tree | 464d2f104f261737c9e6c7ffedabafe023046f1a /railties/doc/guides/source/i18n.txt | |
parent | f333661ec28211b11fad0665b99aad6b0fd23260 (diff) | |
download | rails-44a831940dfab557a525b6a5b132238b53ce9a38.tar.gz rails-44a831940dfab557a525b6a5b132238b53ce9a38.tar.bz2 rails-44a831940dfab557a525b6a5b132238b53ce9a38.zip |
explain exceptions, exception_handler and :raise option
Diffstat (limited to 'railties/doc/guides/source/i18n.txt')
-rw-r--r-- | railties/doc/guides/source/i18n.txt | 47 |
1 files changed, 38 insertions, 9 deletions
diff --git a/railties/doc/guides/source/i18n.txt b/railties/doc/guides/source/i18n.txt index a65fda8d77..572f57f30f 100644 --- a/railties/doc/guides/source/i18n.txt +++ b/railties/doc/guides/source/i18n.txt @@ -276,6 +276,7 @@ I18n.translate :thanks, :name => 'Jeremy' If a translation uses :default or :scope as a interpolation variable an I18n::ReservedInterpolationKey exception is raised. If a translation expects an interpolation variable but it has not been passed to #translate an I18n::MissingInterpolationArgument exception is raised. + === 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 (http://www.unicode.org/cldr/data/charts/supplemental/language_plural_rules.html#ar[Arabic], http://www.unicode.org/cldr/data/charts/supplemental/language_plural_rules.html#ja[Japanese], http://www.unicode.org/cldr/data/charts/supplemental/language_plural_rules.html#ru[Russian] and many more) have different grammars that have additional or less http://www.unicode.org/cldr/data/charts/supplemental/language_plural_rules.html[plural forms]. Thus, the I18n API provides a flexible pluralization feature. @@ -527,19 +528,47 @@ That does not mean you're stuck with these limitations though. The Ruby I18n gem I18n.backend = Globalize::Backend::Static.new ------------------------------------------------------- -TODO expand this ...? list some backends and their features? - === Using different exception handlers -TODO +The I18n API defines the following exceptions that will be raised by backends when the corresponding unexpected conditions occur: + +[source, ruby] +------------------------------------------------------- +MissingTranslationData # no translation was found for the requested key +InvalidLocale # the locale set to I18n.locale is invalid (e.g. nil) +InvalidPluralizationData # a count option was passed but the translation data is not suitable for pluralization +MissingInterpolationArgument # the translation expects an interpolation argument that has not been passed +ReservedInterpolationKey # the translation contains a reserved interpolation variable name (i.e. one of: scope, default) +UnknownFileType # the backend does not know how to handle a file type that was added to I18n.load_path +------------------------------------------------------- -* Explain what exceptions are raised and why we are using exceptions for communication from backend to frontend. -* Explain the default behaviour. -* Explain the :raise option +The I18n API will catch all of these exceptions when they were thrown in the backend and pass them to the default_exception_handler method. This method will re-raise all exceptions except for MissingTranslationData exceptions. When a MissingTranslationData exception has been caught it will return the exception’s error message string containing the missing key/scope. -* Example 1: the Rails #t helper uses a custom exception handler that catches I18n::MissingTranslationData and wraps the message into a span with the CSS class "translation_missing" -* Example 2: for tests you might want a handler that just raises all exceptions all the time -* Example 3: a handler +The reason for this is that during development you'd usually want your views to still render even though a translation is missing. + +In other contexts you might want to change this behaviour though. E.g. the default exception handling does not allow to catch missing translations during automated tests easily. For this purpose a different exception handler can be specified. The specified exception handler must be a method on the I18n module: + +[source, ruby] +------------------------------------------------------- +module I18n + def just_raise_that_exception(*args) + raise args.first + end +end + +I18n.exception_handler = :just_raise_that_exception +------------------------------------------------------- + +This would re-raise all caught exceptions including MissingTranslationData. + +Another example where the default behaviour is less desirable is the Rails TranslationHelper which provides the method #t (as well as #translate). When a MissingTranslationData exception occurs in this context the helper wraps the message into a span with the css class translation_missing. + +To do so the helper forces I18n#translate to raise exceptions no matter what exception handler is defined by setting the :raise option: + +[source, ruby] +------------------------------------------------------- +I18n.t :foo, :raise => true # always re-raises exceptions from the backend +------------------------------------------------------- == Resources |