explain exceptions, exception_handler and :raise option

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