Better docs about overriding third-party translations

javiereguiluz · weaverryan · commit 47bc349b7ebb · 2018-06-21T09:03:34.000-04:00
diff --git a/bundles/override.rst b/bundles/override.rst
@@ -149,8 +149,12 @@ instead of the original ones.
 Translations
 ------------
 
-Translations are not related to bundles, but to domains. That means that you
-can override the translations from any translation file, as long as it is in
-:ref:`the correct domain <using-message-domains>`.
+Translations are not related to bundles, but to :ref:`translation domains <using-message-domains>`.
+For this reason, you can override any bundle translation file from the main
+``translations/`` directory, as long as the new file uses the same domain.
+
+For example, to override the translations defined in the
+``Resources/translations/FOSUserBundle.es.yml`` file of the FOSUserBundle,
+create a``<your-project>/translations/FOSUserBundle.es.yml`` file.
 
 .. _`the Doctrine documentation`: http://docs.doctrine-project.org/projects/doctrine-orm/en/latest/reference/inheritance-mapping.html#overrides
diff --git a/configuration/override_dir_structure.rst b/configuration/override_dir_structure.rst
@@ -129,6 +129,54 @@ own templates directory (or directories):
             ),
         ));
 
+Override the Translations Directory
+-----------------------------------
+
+If your translation files are not stored in the default ``translations/``
+directory, use the :ref:`framework.translator.paths <reference-translator-paths>`
+configuration option to define your own translations directory (or directories):
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/translation.yaml
+        framework:
+            translator:
+                # ...
+                paths: ["%kernel.project_dir%/i18n"]
+
+    .. code-block:: xml
+
+        <!-- config/packages/translation.xml -->
+        <?xml version="1.0" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:twig="http://symfony.com/schema/dic/twig"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                http://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/twig
+                http://symfony.com/schema/dic/twig/twig-1.0.xsd">
+
+            <framework:config>
+                <framework:translator>
+                    <framework:path>%kernel.project_dir%/i18n</framework:path>
+                </framework:translator>
+            </framework:config>
+
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/translation.php
+        $container->loadFromExtension('framework', array(
+            'translator' => array(
+                'paths' => array(
+                    '%kernel.project_dir%/i18n',
+                ),
+            ),
+        ));
+
 .. _override-web-dir:
 .. _override-the-web-directory:
 
