From 14544f8f1500ad1bec7c3bd2e6d2664a8b85676b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Szymon=20Kami=C5=84ski?= <kaminskisj@gmail.com>
Date: Mon, 25 Sep 2023 09:34:06 +0200
Subject: [PATCH] [Translation] Add information about custom providers

---
 reference/dic_tags.rst | 44 ++++++++++++++++++++++++++++++++++++++++++
 translation.rst        | 11 +++++++++++
 2 files changed, 55 insertions(+)

diff --git a/reference/dic_tags.rst b/reference/dic_tags.rst
index 5b035d6f89b..630829c747a 100644
--- a/reference/dic_tags.rst
+++ b/reference/dic_tags.rst
@@ -1228,6 +1228,50 @@ This is the name that's used to determine which dumper should be used.
         $container->register(JsonFileDumper::class)
             ->addTag('translation.dumper', ['alias' => 'json']);
 
+.. _reference-dic-tags-translation-provider-factory:
+
+translation.provider_factory
+----------------------------
+
+**Purpose**: To register a factory creating custom Translation Provider
+
+Register your factory as a service and tag it with ``translation.provider_factory``:
+
+.. configuration-block::
+
+    .. code-block:: yaml
+
+        services:
+            App\Translation\CustomProviderFactory:
+                tags:
+                    - { name: translation.provider_factory }
+
+    .. code-block:: 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"
+            xsi:schemaLocation="http://symfony.com/schema/dic/services
+                https://symfony.com/schema/dic/services/services-1.0.xsd">
+
+            <services>
+                <service id="App\Translation\CustomProviderFactory">
+                    <tag name="translation.provider_factory"/>
+                </service>
+            </services>
+        </container>
+
+    .. code-block:: php
+
+        use App\Translation\CustomProviderFactory;
+
+        $container
+            ->register(CustomProviderFactory::class)
+            ->addTag('translation.provider_factory')
+        ;
+
+For more details, see :ref:`translation providers <translation-providers>`.
+
 .. _reference-dic-tags-twig-extension:
 
 twig.extension
diff --git a/translation.rst b/translation.rst
index ffaca50044d..7423695dc07 100644
--- a/translation.rst
+++ b/translation.rst
@@ -746,6 +746,17 @@ now use the following commands to push (upload) and pull (download) translations
     # check out the command help to see its options (format, domains, locales, intl-icu, etc.)
     $ php bin/console translation:pull --help
 
+Creating custom Provider
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you wish to create new Translation Provider, you need to create two classes.
+First one must implement :class:`Symfony\\Component\\Translation\\Provider\\ProviderInterface`.
+Second needs to be a factory, that will create instances of the first class. It must implement
+:class:`Symfony\\Component\\Translation\\Provider\\ProviderFactoryInterface`.
+You may extend :class:`Symfony\\Component\\Translation\\Provider\\AbstractProviderFactory`
+to simplify its creation. Additionally you need to tag the factory service with
+:ref:`translation.provider_factory <reference-dic-tags-translation-provider-factory>`.
+
 .. _translation-locale:
 
 Handling the User's Locale