[Translation] Document the enabled_locales option

javiereguiluz · javiereguiluz · commit e9725317492f · 2020-02-13T13:29:10.000+01:00
diff --git a/performance.rst b/performance.rst
@@ -13,6 +13,7 @@ Symfony Application Checklist
 
 #. :ref:`Install APCu Polyfill if your server uses APC <performance-install-apcu-polyfill>`
 #. :ref:`Dump the service container into a single file <performance-service-container-single-file>`
+#. :ref:`Restrict the number of locales enabled in the application <performance-enabled-locales>`
 
 Production Server Checklist
 ---------------------------
@@ -74,6 +75,14 @@ container into a single file, which could improve performance when using
         // ...
         $container->setParameter('container.dumper.inline_factories', true);
 
+.. _performance-enabled-locales:
+
+Restrict the number of locales enabled in the application
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Use the :ref:`framework.translator.enabled_locales <reference-translator-enabled-locales>`
+option to only generate the translation files actually used in your application.
+
 .. _performance-use-opcache:
 
 Use the OPcache Byte Code Cache
diff --git a/reference/configuration/framework.rst b/reference/configuration/framework.rst
@@ -227,6 +227,7 @@ Configuration
   * `cache_dir`_
   * :ref:`default_path <reference-translator-default_path>`
   * :ref:`enabled <reference-translator-enabled>`
+  * :ref:`enabled_locales <reference-translator-enabled-locales>`_
   * `fallbacks`_
   * `formatter`_
   * `logging`_
@@ -1989,6 +1990,64 @@ enabled
 
 Whether or not to enable the ``translator`` service in the service container.
 
+.. _reference-translator-enabled-locales:
+
+enabled_locales
+...............
+
+**type**: ``array`` **default**: ``[]`` (empty array)
+
+.. versionadded:: 5.1
+
+    The ``enabled_locales`` option was introduced in Symfony 5.1.
+
+Symfony applications enable by default all locales. This means that Symfony
+generates and tracks tens of translation files (for the validation and security
+messages). If your application only uses some locales, use this option to
+restrict the files generated by Symfony and improve performance a bit:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        # config/packages/translation.yaml
+        framework:
+            translation:
+                enabled_locales: ['en', 'es']
+
+    .. code-block:: xml
+
+        <!-- config/packages/translation.xml -->
+        <?xml version="1.0" encoding="UTF-8" ?>
+        <container xmlns="http://symfony.com/schema/dic/services"
+            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+            xmlns:framework="http://symfony.com/schema/dic/symfony"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd
+                http://symfony.com/schema/dic/symfony https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
+
+            <framework:config>
+                <framework:translation>
+
+                    ?????
+
+                </framework:translation>
+            </framework:config>
+        </container>
+
+    .. code-block:: php
+
+        // config/packages/translation.php
+        $container->loadFromExtension('framework', [
+            'translation' => [
+                'enabled_locales' => ['en', 'es'],
+            ],
+        ]);
+
+If some user makes requests with a locale not included in this option, the
+application won't display any error because Symfony will display contents using
+the fallback locale.
+
 .. _fallback:
 
 fallbacks
