Added a new section "Extracting Translation Contents and Updating Cat…

translation.rst

@@ -107,13 +107,12 @@ of text (called a *message*), use the
 for example, that you're translating a simple message from inside a controller::
 
     // ...
-    use Symfony\Component\HttpFoundation\Response;
 
     public function indexAction()
     {
         $translated = $this->get('translator')->trans('Symfony is great');
 
-        return new Response($translated);
+        // ...
     }
 
 .. _translation-resources:
@@ -185,13 +184,11 @@ Message Placeholders
 
 Sometimes, a message containing a variable needs to be translated::
 
-    use Symfony\Component\HttpFoundation\Response;
-
     public function indexAction($name)
     {
         $translated = $this->get('translator')->trans('Hello '.$name);
 
-        return new Response($translated);
+        // ...
     }
 
 However, creating a translation for this string is impossible since the translator
@@ -258,11 +255,11 @@ You can also specify the message domain and pass some additional variables:
 
 .. code-block:: twig
 
-    {% trans with {'%name%': 'Fabien'} from "app" %}Hello %name%{% endtrans %}
+    {% trans with {'%name%': 'Fabien'} from 'app' %}Hello %name%{% endtrans %}
 
-    {% trans with {'%name%': 'Fabien'} from "app" into "fr" %}Hello %name%{% endtrans %}
+    {% trans with {'%name%': 'Fabien'} from 'app' into 'fr' %}Hello %name%{% endtrans %}
 
-    {% transchoice count with {'%name%': 'Fabien'} from "app" %}
+    {% transchoice count with {'%name%': 'Fabien'} from 'app' %}
         {0} %name%, there are no apples|{1} %name%, there is one apple|]1,Inf[ %name%, there are %count% apples
     {% endtranschoice %}
 
@@ -277,7 +274,7 @@ texts* and complex expressions:
 
     {{ message|transchoice(5) }}
 
-    {{ message|trans({'%name%': 'Fabien'}, "app") }}
+    {{ message|trans({'%name%': 'Fabien'}, 'app') }}
 
     {{ message|transchoice(5, {'%name%': 'Fabien'}, 'app') }}
 
@@ -308,7 +305,7 @@ texts* and complex expressions:
 
     .. code-block:: twig
 
-           {% trans_default_domain "app" %}
+           {% trans_default_domain 'app' %}
 
     Note that this only influences the current template, not any "included"
     template (in order to avoid side effects).
@@ -329,6 +326,44 @@ The translator service is accessible in PHP templates through the
         array('%count%' => 10)
     ) ?>
 
+Extracting Translation Contents and Updating Catalogs Automatically
+-------------------------------------------------------------------
+
+The most time-consuming task when translating an application is to extract all
+the template contents to be translated and to keep all the translation files in
+sync. Symfony includes a command called ``translation:update`` that helps you in
+these tasks.
+
+The "safe mode" of this command uses the ``--dump-messages`` option to output
+in the command console the strings to be translated:
+
+.. code-block:: terminal
+
+    # shows the strings to be translated into French for app/Resources/ templates
+    $ ./app/console translation:update --dump-messages fr
+
+    # shows the strings to be translated into English for the AppBundle templates
+    $ ./app/console translation:update --dump-messages en AppBundle
+
+The "advanced mode" of this command uses the ``--force`` option to actually
+update the contents of the translation files to add the missing strings:
+
+.. code-block:: terminal
+
+    # updates the French translation file to add the missing strings
+    # found on app/Resources/ templates
+    $ ./app/console translation:update --force fr
+
+    # updates the English translation file to add the missing strings
+    # found on AppBundle templates
+    $ ./app/console translation:update --force en AppBundle
+
+.. tip::
+
+    If you need to extract translation strings from other sources, such as
+    controllers, forms and flash messages, consider using the more advanced
+    `TranslationBundle`_ third-party bundle.
+
 .. _translation-resource-locations:
 
 Translation Resource/File Names and Locations
@@ -412,8 +447,8 @@ checks translation resources for several locales:
 
 .. note::
 
-    When Symfony doesn't find a translation in the given locale, it will 
-    add the missing translation to the log file. For details, 
+    When Symfony doesn't find a translation in the given locale, it will
+    add the missing translation to the log file. For details,
     see :ref:`reference-framework-translator-logging`.
 
 Handling the User's Locale
@@ -470,3 +505,4 @@ Learn more
 .. _`ISO 639-1`: https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes
 .. _`Translatable Extension`: http://atlantic18.github.io/DoctrineExtensions/doc/translatable.html
 .. _`Translatable Behavior`: https://github.com/KnpLabs/DoctrineBehaviors
+.. _`TranslationBundle`: https://github.com/php-translation/symfony-bundle