Reread component docs

wouterj · weaverryan · commit 56b02be28c2e · 2013-11-16T15:03:28.000-06:00
diff --git a/components/translation/introduction.rst b/components/translation/introduction.rst
@@ -19,15 +19,17 @@ You can install the component in many different ways:
 Constructing the Translator
 ---------------------------
 
-Before you can use the Translator, you need to configure it and load the
-message catalogues.
+The main access point of the Translation Component is
+:class:`Symfony\\Component\\Translation\\Translator`. Before you can use it,
+you need to configure it and load the messages to translate (called *message
+catalogues*).
 
 Configuration
 ~~~~~~~~~~~~~
 
-The constructor of the ``Translator`` class needs to arguments: The locale and
-a :class:`Symfony\\Component\\Translation\\MessageSelector` to use when using
-pluralization (more about that later)::
+The constructor of the ``Translator`` class needs two arguments: The locale
+and the :class:`Symfony\\Component\\Translation\\MessageSelector` to use when
+using pluralization (more about that later)::
 
     use Symfony\Component\Translation\Translator;
     use Symfony\Component\Translation\MessageSelector;
@@ -56,9 +58,9 @@ Loader too. The default loaders are:
 * :class:`Symfony\\Component\\Translation\\Loader\\ArrayLoader` - to load
   catalogues from PHP arrays.
 * :class:`Symfony\\Component\\Translation\\Loader\\CsvFileLoader` - to load
-  catalogues from Csv files.
+  catalogues from CSV files.
 * :class:`Symfony\\Component\\Translation\\Loader\\PhpFileLoader` - to load
-  catalogues from Php files.
+  catalogues from PHP files.
 * :class:`Symfony\\Component\\Translation\\Loader\\XliffFileLoader` - to load
   catalogues from Xliff files.
 * :class:`Symfony\\Component\\Translation\\Loader\\YamlFileLoader` - to load
@@ -67,21 +69,21 @@ Loader too. The default loaders are:
 All loaders, except the ``ArrayLoader``, requires the
 :doc:`Config component</components/config/index>`.
 
-At first, you should add a loader to the ``Translator``::
+At first, you should add one or more loaders to the ``Translator``::
 
     // ...
     $translator->addLoader('array', new ArrayLoader());
 
-The first argument is the key to which we can refer the loader in the translator
-and the second argument is an instance of the loader itself. After this, you
-can add your resources using the correct loader.
+The first argument is the name to which you can refer the loader in the
+translator and the second argument is an instance of the loader itself. After
+this, you can add your resources using the correct loader.
 
 Loading Messages with the ``ArrayLoader``
 .........................................
 
 Loading messages can be done by calling
 :method:`Symfony\\Component\\Translation\\Translator::addResource`. The first
-argument is the loader name (the first argument of the ``addLoader``
+argument is the loader name (this was the first argument of the ``addLoader``
 method), the second is the resource and the third argument is the locale::
 
     // ...
@@ -106,24 +108,26 @@ The Translation Process
 To actually translate the message, the Translator uses a simple process:
 
 * A catalog of translated messages is loaded from translation resources defined
-  for the ``locale`` (e.g. ``fr_FR``). Messages from the fallback locale are
-  also loaded and added to the catalog if they don't already exist. The end
-  result is a large "dictionary" of translations;
+  for the ``locale`` (e.g. ``fr_FR``). Messages from the
+  :ref:`fallback locale <Fallback Locale>` are also loaded and added to the
+  catalog if they don't already exist. The end result is a large "dictionary"
+  of translations;
 
 * If the message is located in the catalog, the translation is returned. If
   not, the translator returns the original message.
 
 You start this process by calling
-:method:`Symfony\\Component\\Translation\\Translator::trans`. Then, the
+:method:`Symfony\\Component\\Translation\\Translator::trans` or
+:method:`Symfony\\Component\\Translation\\Translator::transChoice`. Then, the
 Translator looks for the exact string inside the appropriate message catalog
 and returns it (if it exists).
 
 .. tip::
 
     When a translation does not exist for a locale, the translator first tries
-    to find the translation for the language (``fr`` if the locale is
-    ``fr_FR`` for instance). If this also fails, it looks for a translation
-    using the fallback locale.
+    to find the translation for the language (e.g. ``fr`` if the locale is
+    ``fr_FR``). If this also fails, it looks for a translation using the
+    fallback locale.
 
 Fallback Locale
 ~~~~~~~~~~~~~~~
