From 33b2150f2ddc9b2c8ef5adcb28e6f0e21133baf9 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 13 Feb 2017 15:12:48 +0100 Subject: [PATCH 1/3] Added a new section "Extracting Translation Contents and Updating Catalogs Automatically" --- translation.rst | 59 +++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 47 insertions(+), 12 deletions(-) diff --git a/translation.rst b/translation.rst index 418d7711369..aab2610ada8 100644 --- a/translation.rst +++ b/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,43 @@ 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 original contents added to the templates 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 + $ ./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 --dump-messages fr + + # updates the English translation file to add the missing strings found on AppBundle + $ ./app/console translation:update --dump-messages 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 +446,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 +504,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 From c83f3144d310525e08563e44373c5c7524833337 Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Mon, 13 Feb 2017 16:05:59 +0100 Subject: [PATCH 2/3] Minor fixes --- translation.rst | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/translation.rst b/translation.rst index aab2610ada8..86a9ecd0a5e 100644 --- a/translation.rst +++ b/translation.rst @@ -330,9 +330,9 @@ Extracting Translation Contents and Updating Catalogs Automatically ------------------------------------------------------------------- The most time-consuming task when translating an application is to extract all -the original contents added to the templates and to keep all the translation -files in sync. Symfony includes a command called ``translation:update`` that -helps you in these tasks. +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: @@ -342,7 +342,7 @@ in the command console the strings to be translated: # 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 + # 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 @@ -352,10 +352,11 @@ update the contents of the translation files to add the missing strings: # updates the French translation file to add the missing strings # found on app/Resources/ templates - $ ./app/console translation:update --dump-messages fr + $ ./app/console translation:update --force fr - # updates the English translation file to add the missing strings found on AppBundle - $ ./app/console translation:update --dump-messages en AppBundle + # updates the English translation file to add the missing strings + # found on AppBundle templates + $ ./app/console translation:update --force en AppBundle .. tip:: From c2f0166ab87c6216fb334fb5f4bc49ccc3f99fae Mon Sep 17 00:00:00 2001 From: Javier Eguiluz Date: Thu, 11 Jan 2018 09:26:09 +0100 Subject: [PATCH 3/3] Simplified everything as suggested by reviewers --- translation.rst | 33 +++++++++++---------------------- 1 file changed, 11 insertions(+), 22 deletions(-) diff --git a/translation.rst b/translation.rst index 86a9ecd0a5e..2dc91ef9eb5 100644 --- a/translation.rst +++ b/translation.rst @@ -329,40 +329,29 @@ The translator service is accessible in PHP templates through the Extracting Translation Contents and Updating Catalogs Automatically ------------------------------------------------------------------- -The most time-consuming task when translating an application is to extract all +The most time-consuming tasks 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: +sync. Symfony includes a command called ``translation:update`` that helps you +with these tasks: .. 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 + # updates the French translation file with the missing strings found in app/Resources/ templates + $ ./app/console translation:update --dump-messages --force fr -The "advanced mode" of this command uses the ``--force`` option to actually -update the contents of the translation files to add the missing strings: + # updates the English translation file with the missing strings found in AppBundle + $ ./app/console translation:update --dump-messages --force en AppBundle -.. code-block:: terminal - - # updates the French translation file to add the missing strings - # found on app/Resources/ templates - $ ./app/console translation:update --force fr +.. note:: - # updates the English translation file to add the missing strings - # found on AppBundle templates - $ ./app/console translation:update --force en AppBundle + If you want to see the missing translation strings without actually updating + the translation files, remove the ``--force`` option from the command above. .. 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. + third-party `TranslationBundle`_. .. _translation-resource-locations: