8000 Added documentation for translation:debug by florianv · Pull Request #3629 · symfony/symfony-docs · GitHub
[go: up one dir, main page]
Skip to content

Added documentation for translation:debug #3629

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 4 commits into from
Mar 17, 2014
Merged

Added documentation for translation:debug #3629

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2d9647b
Added documentation for translation:debug
florianv Mar 3, 2014
864b9f2
Merge branch 'master' of github.com:symfony/symfony-docs into transla…
florianv Mar 13, 2014
38b2955
Improved the documentation with examples and images
florianv Mar 13, 2014
b6ac454
Fixed the issues
florianv Mar 13, 2014
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Fixed the issues
  • Loading branch information
@florianv
florianv committed Mar 13, 2014
commit b6ac4540c0b95f1bcdd47c26db126336cd0535f2
47 changes: 28 additions & 19 deletions book/translation.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -673,28 +673,38 @@ tag or filter usages in Twig templates:

{{ 'Symfony2 is great'|trans }}
Copy link
Member

Choose a reason for hiding this comment

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

I would add an example using transchoice as well, which is detected


{{ 'Symfony2 is great'|transchoice(1) }}

{% transchoice 1 %}Symfony2 is great{% endtranschoice %}

It will also detect the following translator usages in PHP templates:

.. code-block:: php

$view['translator']->trans("Symfony2 is great");

$view['translator']->trans(‘Symfony2 is great’);
$view['translator']->trans('Symfony2 is great');

.. caution::

Supposing your application default_locale is French ``fr`` and you have enabled
the translator in your configuration with English ``en`` as fallback locale.
The extractors are not able to inspect the messages translated outside templates which means
that translator usages in form labels or inside your controllers won't be detected.
Copy link
Member

Choose a reason for hiding this comment

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

the extractor is not able to extract template translations involving a variable either like this:

{% set message = 'Symfony2 is great' %}
{{ message|trans }}

Dynamic translations involving variables or expressions are not detected in templates,
which means this example won't be analyzed:

See :ref:`book-translation-configuration` and :ref:`book-translation-fallback` for details
about how to configure these.
.. code-block:: jinja
{% set message = 'Symfony2 is great' %}
{{ message|trans }}

You are working on the AcmeDemoBundle and the translation file for the ``messages`` domain
in the ``fr`` locale contains:
Suppose your application's default_locale is ``fr`` and you have configured ``en`` as the fallback locale
(see :ref:`book-translation-configuration` and :ref:`book-translation-fallback` for how to configure these).
And suppose you've already setup some translations for the ``fr`` locale inside an AcmeDemoBundle:

.. configuration-block::

.. code-block:: xml

<!-- messages.fr.xliff -->
<!-- src/Acme/AcmeDemoBundle/Resources/translations/messages.fr.xliff -->
<?xml version="1.0"?>
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
<file source-language="en" datatype="plaintext" original="file.ext">
Expand All @@ -709,14 +719,14 @@ in the ``fr`` locale contains:

.. code-block:: php

// messages.fr.php
// src/Acme/AcmeDemoBundle/Resources/translations/messages.fr.php
return array(
'Symfony2 is great' => 'J\'aime Symfony2',
);

.. code-block:: yaml

# messages.fr.yml
# src/Acme/Acm 8000 eDemoBundle/Resources/translations/messages.fr.yml
Symfony2 is great: J'aime Symfony2

and for the ``en`` locale:
Expand All @@ -725,7 +735,7 @@ and for the ``en`` locale:

.. code-block:: xml

<!-- messages.en.xliff -->
<!-- src/Acme/AcmeDemoBundle/Resources/translations/messages.en.xliff -->
<?xml version="1.0"?>
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
<file source-language="en" datatype="plaintext" original="file.ext">
Expand All @@ -740,14 +750,14 @@ and for the ``en`` locale:

.. code-block:: php

// messages.en.php
// src/Acme/AcmeDemoBundle/Resources/translations/messages.en.php
return array(
'Symfony2 is great' => 'Symfony2 is great',
);

.. code-block:: yaml

# messages.en.yml
# src/Acme/AcmeDemoBundle/Resources/translations/messages.en.yml
Symfony2 is great: Symfony2 is great

To inspect all messages in the ``fr`` locale for the AcmeDemoBundle, run:
Expand All @@ -761,16 +771,15 @@ You will get this output:
.. image:: /images/book/translation/debug_1.png
:align: center

It indicates the message with id ``Symfony2 is great`` is unused because it is translated
but we don’t use it in any template yet.
It indicates that the message ``Symfony2 is great`` is unused because it is translated,
but you haven't used it anywhere yet.

Now, if you translate the message in one of your templates, you will get this output:
Copy link
Member

Choose a reason for hiding this comment

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

... if you translate the message somewhere (e.g. like in a template), you will ...

Copy link
Contributor Author

Choose a reason for hiding this comment

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

The extractors will detect only the usages in the templates, I think it deserves a warning as @stof mentionned.
Maybe around line 683 after explaining the extractors ?


.. image:: /images/book/translation/debug_2.png
:align: center

The state is empty which means the message is translated in the ``fr`` locale and used in one or more templates.
Moreover, we see the translation is different than the ``en`` one.

If you delete the message ``Symfony2 is great`` from your translation file for the ``fr`` locale
and run the command, you will get:
Expand All @@ -780,7 +789,7 @@ and run the command, you will get:

The state indicates the message is missing because it is not translated in the ``fr`` locale
but it is still used in the template.
Copy link
Member

Choose a reason for hiding this comment

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

we can add a little emphasis :)

but it is still

Moreover, we see the message in the ``fr`` locale equals to the message in the ``en`` locale.
Moreover, the message in the ``fr`` locale equals to the message in the ``en`` locale.
This is a special case because the untranslated message id equals its translation in the ``en`` locale.

If you copy the content of the translation file in the ``en`` locale, to the translation file
Expand All @@ -789,8 +798,8 @@ in the ``fr`` locale and run the command, you will get:
.. image:: /images/book/translation/debug_4.png
:align: center

We observe the translations of the message are identical in the ``fr`` and ``en`` locales
which means this message was probably copied from French to English or vice versa (which is the case).
You can see that the translations of the message are identical in the ``fr`` and ``en`` locales
which means this message was probably copied from French to English and maybe you forgot to translate it.

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

Expand Down
0