Skip to content
Closed
Changes from 1 commit
Commits
File filter

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Next Next commit
Added a new section "Extracting Translation Contents and Updating Cat…
…alogs Automatically"
  • Loading branch information
javiereguiluz committed Feb 13, 2017
commit 33b2150f2ddc9b2c8ef5adcb28e6f0e21133baf9
59 changes: 47 additions & 12 deletions translation.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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 %}

Expand All @@ -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') }}

Expand Down Expand Up @@ -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).
Expand All @@ -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:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[...] to output the strings to be translated:

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should remove this - let's just show the commands below


.. 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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[...] third-party TranslationBundle.


.. _translation-resource-locations:

Translation Resource/File Names and Locations
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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