Re-wrote intro section w/r/t to i18n/L18n difference, more concrete description

1 files changed, 15 insertions, 5 deletions

diff --git a/railties/doc/guides/source/i18n.txt b/railties/doc/guides/source/i18n.txt
index ca8bf2f783..2ec28cd3d8 100644
--- a/railties/doc/guides/source/i18n.txt
+++ b/railties/doc/guides/source/i18n.txt
@@ -3,10 +3,19 @@ The 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.
 
-In the process of _localizing_ your application you'll probably want to do following two things:
+The process of "internationalization" usually means to abstract all strings and other locale specific bits (such as date or currency formats) out of your application. The process of "localization" means to provide translations and localized formats for these bits. <<1>>
+
+So, in the process of _internationalizing_ your Rails application you have to:
+
+* Ensure you have support for i18n
+* 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:
 
 * Replace or supplement Rail's default locale -- eg. date and time formats, month names, ActiveRecord model names, etc
 * Abstract texts in your application into keyed dictionaries -- eg. flash messages, static texts 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.
 
@@ -284,13 +293,14 @@ IMPORTANT: This solution has currently one rather big *downside*. Due to the _de
 
 # TODO: Accept-Language, GeoIP, etc. Explain why it is not such a good idea in most cases.
 
-OK! Now you've initialized I18n support for your application and told it which locale should be used and how to preserve it between requests. With that in place you're now ready for the really interesting stuff.
 
-== Internationalize your application
+== Internationalizing your application
+
+OK! Now you've initialized I18n support for your Ruby on Rails application and told it which locale should be used and how to preserve it between requests. With that in place you're now ready for the really interesting stuff.
 
-The process of "internationalization" usually means to abstract all strings and other locale specific bits out of your application. The process of "localization" means to then provide translations and localized formats for these bits. <<1>>
+Let's _internationalize_ our application, ie. abstract every locale-specific parts, and that _localize_ it, ie. provide neccessary translations for these abstracts. 
 
-So, let's internationalize something. You most probably have something like this in one of your applications:
+You most probably have something like this in one of your applications:
 
 [source, ruby]
 -------------------------------------------------------