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