diff --git a/book/translation.rst b/book/translation.rst
index cef3223a024..0c7e13e77ae 100644
--- a/book/translation.rst
+++ b/book/translation.rst
@@ -649,6 +649,172 @@ The translation of database content should be handled by Doctrine through
the `Translatable Extension`_ or the `Translatable Bahavior`_ (PHP 5.4+).
For more information, see the documentation for thes libraries.
+Debugging Translations
+----------------------
+
+.. versionadded:: 2.5
+ The ``translation:debug`` command was introduced in Symfony 2.5.
+
+When maintaining a bundle, you may use or remove the usage of a translation
+message without updating all message catalogues. The ``translation:debug``
+command helps you to find these missing or unused translation messages for a
+given locale. It shows you a table with the result when translating the
+message in the given locale and the result when the fallback would be used.
+On top of that, it also shows you when the translation is the same as the
+fallback translation (this could indicate that the message was not correctly
+translated).
+
+Thanks to the messages extractors, the command will detect the translation
+tag or filter usages in Twig templates:
+
+.. code-block:: jinja
+
+ {% trans %}Symfony2 is great{% endtrans %}
+
+ {{ 'Symfony2 is great'|trans }}
+
+ {{ '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');
+
+.. caution::
+
+ 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.
+ Dynamic translations involving variables or expressions are not detected in templates,
+ which means this example won't be analyzed:
+
+ .. code-block:: jinja
+ {% set message = 'Symfony2 is great' %}
+ {{ message|trans }}
+
+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
+
+
+
+
+
+
+
+ Symfony2 is great
+ J'aime Symfony2
+
+
+
+
+
+ .. code-block:: php
+
+ // src/Acme/AcmeDemoBundle/Resources/translations/messages.fr.php
+ return array(
+ 'Symfony2 is great' => 'J\'aime Symfony2',
+ );
+
+ .. code-block:: yaml
+
+ # src/Acme/AcmeDemoBundle/Resources/translations/messages.fr.yml
+ Symfony2 is great: J'aime Symfony2
+
+and for the ``en`` locale:
+
+.. configuration-block::
+
+ .. code-block:: xml
+
+
+
+
+
+
+
+ Symfony2 is great
+ Symfony2 is great
+
+
+
+
+
+ .. code-block:: php
+
+ // src/Acme/AcmeDemoBundle/Resources/translations/messages.en.php
+ return array(
+ 'Symfony2 is great' => 'Symfony2 is great',
+ );
+
+ .. code-block:: yaml
+
+ # 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:
+
+.. code-block:: bash
+
+ $ php app/console translation:debug fr AcmeDemoBundle
+
+You will get this output:
+
+.. image:: /images/book/translation/debug_1.png
+ :align: center
+
+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:
+
+.. 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.
+
+If you delete the message ``Symfony2 is great`` from your translation file for the ``fr`` locale
+and run the command, you will get:
+
+.. image:: /images/book/translation/debug_3.png
+ :align: center
+
+The state indicates the message is missing because it is not translated in the ``fr`` locale
+but it is still used in the template.
+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
+in the ``fr`` locale and run the command, you will get:
+
+.. image:: /images/book/translation/debug_4.png
+ :align: center
+
+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:
+
+.. code-block:: bash
+
+ $ php app/console translation:debug en AcmeDemoBundle --domain=messages
+
+When bundles have a lot of messages, it is useful to display only the unused
+or only the missing messages, by using the ``--only-unused`` or ``--only-missing`` switches:
+
+.. code-block:: bash
+
+ $ php app/console translation:debug en AcmeDemoBundle --only-unused
+ $ php app/console translation:debug en AcmeDemoBundle --only-missing
+
Summary
-------
diff --git a/images/book/translation/debug_1.png b/images/book/translation/debug_1.png
new file mode 100644
index 00000000000..8f175f4d7ff
Binary files /dev/null and b/images/book/translation/debug_1.png differ
diff --git a/images/book/translation/debug_2.png b/images/book/translation/debug_2.png
new file mode 100644
index 00000000000..04a57fa41d4
Binary files /dev/null and b/images/book/translation/debug_2.png differ
diff --git a/images/book/translation/debug_3.png b/images/book/translation/debug_3.png
new file mode 100644
index 00000000000..6ed595e097b
Binary files /dev/null and b/images/book/translation/debug_3.png differ
diff --git a/images/book/translation/debug_4.png b/images/book/translation/debug_4.png
new file mode 100644
index 00000000000..db642b1773f
Binary files /dev/null and b/images/book/translation/debug_4.png differ