Skip to content

Commit 38b2955

Browse files
florianvflorianv
committed
Improved the documentation with examples and images
1 parent 864b9f2 commit 38b2955

File tree

5 files changed

+129
-5
lines changed

5 files changed

+129
-5
lines changed

‎book/translation.rst

+129-5
Original file line numberDiff line numberDiff line change
@@ -657,25 +657,149 @@ Debugging Translations
657657

658658
When maintaining a bundle, you may use or remove the usage of a translation
659659
message without updating all message catalogues. The ``translation:debug``
660-
command helps you finding these missing or unused translation messages for a
660+
command helps you to find these missing or unused translation messages for a
661661
given locale. It shows you a table with the result when translating the
662662
message in the given locale and the result when the fallback would be used.
663663
On top of that, it also shows you when the translation is the same as the
664664
fallback translation (this could indicate that the message was not correctly
665-
translated). To inspect all messages in the ``en`` locale for the AcmeDemoBundle, run:
665+
translated).
666+
667+
Thanks to the messages extractors, the command will detect the translation
668+
tag or filter usages in Twig templates:
669+
670+
.. code-block:: jinja
671+
672+
{% trans %}Symfony2 is great{% endtrans %}
673+
674+
{{ 'Symfony2 is great'|trans }}
675+
676+
It will also detect the following translator usages in PHP templates:
677+
678+
.. code-block:: php
679+
680+
$view['translator']->trans("Symfony2 is great");
681+
682+
$view['translator']->trans(‘Symfony2 is great’);
683+
684+
Supposing your application default_locale is French ``fr`` and you have enabled
685+
the translator in your configuration with English ``en`` as fallback locale.
686+
687+
See :ref:`book-translation-configuration` and :ref:`book-translation-fallback` for details
688+
about how to configure these.
689+
690+
You are working on the AcmeDemoBundle and the translation file for the ``messages`` domain
691+
in the ``fr`` locale contains:
692+
693+
.. configuration-block::
694+
695+
.. code-block:: xml
696+
697+
<!-- messages.fr.xliff -->
698+
<?xml version="1.0"?>
699+
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
700+
<file source-language="en" datatype="plaintext" original="file.ext">
701+
<body>
702+
<trans-unit id="1">
703+
<source>Symfony2 is great</source>
704+
<target>J'aime Symfony2</target>
705+
</trans-unit>
706+
</body>
707+
</file>
708+
</xliff>
709+
710+
.. code-block:: php
711+
712+
// messages.fr.php
713+
return array(
714+
'Symfony2 is great' => 'J\'aime Symfony2',
715+
);
716+
717+
.. code-block:: yaml
718+
719+
# messages.fr.yml
720+
Symfony2 is great: J'aime Symfony2
721+
722+
and for the ``en`` locale:
723+
724+
.. configuration-block::
725+
726+
.. code-block:: xml
727+
728+
<!-- messages.en.xliff -->
729+
<?xml version="1.0"?>
730+
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
731+
<file source-language="en" datatype="plaintext" original="file.ext">
732+
<body>
733+
<trans-unit id="1">
734+
<source>Symfony2 is great</source>
735+
<target>Symfony2 is great</target>
736+
</trans-unit>
737+
</body>
738+
</file>
739+
</xliff>
740+
741+
.. code-block:: php
742+
743+
// messages.en.php
744+
return array(
745+
'Symfony2 is great' => 'Symfony2 is great',
746+
);
747+
748+
.. code-block:: yaml
749+
750+
# messages.en.yml
751+
Symfony2 is great: Symfony2 is great
752+
753+
To inspect all messages in the ``fr`` locale for the AcmeDemoBundle, run:
666754

667755
.. code-block:: bash
668756
669-
$ php app/console translation:debug en AcmeDemoBundle
757+
$ php app/console translation:debug fr AcmeDemoBundle
758+
759+
You will get this output:
760+
761+
.. image:: /images/book/translation/debug_1.png
762+
:align: center
763+
764+
It indicates the message with id ``Symfony2 is great`` is unused because it is translated
765+
but we don’t use it in any template yet.
766+
767+
Now, if you translate the message in one of your templates, you will get this output:
768+
769+
.. image:: /images/book/translation/debug_2.png
770+
:align: center
771+
772+
The state is empty which means the message is translated in the ``fr`` locale and used in one or more templates.
773+
Moreover, we see the translation is different than the ``en`` one.
774+
775+
If you delete the message ``Symfony2 is great`` from your translation file for the ``fr`` locale
776+
and run the command, you will get:
777+
778+
.. image:: /images/book/translation/debug_3.png
779+
:align: center
780+
781+
The state indicates the message is missing because it is not translated in the ``fr`` locale
782+
but it is still used in the template.
783+
Moreover, we see the message in the ``fr`` locale equals to the message in the ``en`` locale.
784+
This is a special case because the untranslated message id equals its translation in the ``en`` locale.
785+
786+
If you copy the content of the translation file in the ``en`` locale, to the translation file
787+
in the ``fr`` locale and run the command, you will get:
788+
789+
.. image:: /images/book/translation/debug_4.png
790+
:align: center
791+
792+
We observe the translations of the message are identical in the ``fr`` and ``en`` locales
793+
which means this message was probably copied from French to English or vice versa (which is the case).
670794

671795
By default all domains are inspected, but it is possible to specify a single domain:
672796

673797
.. code-block:: bash
674798
675799
$ php app/console translation:debug en AcmeDemoBundle --domain=messages
676800
677-
You can also display only the unused or only the missing messages, by using
678-
the ``--only-unused`` or ``--only-missing`` switches:
801+
When bundles have a lot of messages, it is useful to display only the unused
802+
or only the missing messages, by using the ``--only-unused`` or ``--only-missing`` switches:
679803

680804
.. code-block:: bash
681805

‎images/book/translation/debug_1.png

22.2 KB
Loading

‎images/book/translation/debug_2.png

22 KB
Loading

‎images/book/translation/debug_3.png

21.9 KB
Loading

‎images/book/translation/debug_4.png

21.7 KB
Loading

0 commit comments

Comments
 (0)