Skip to content

Commit 5d3ef38

Browse files
welcoMatticwelcoMattic
committed
Introduce Translation Providers
1 parent d7d3f7c commit 5d3ef38

File tree

2 files changed

+166
-0
lines changed

2 files changed

+166
-0
lines changed

‎reference/configuration/framework.rst

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -283,6 +283,7 @@ Configuration
283283
* `formatter`_
284284
* `logging`_
285285
* :ref:`paths <reference-translator-paths>`
286+
* :ref:`providers <reference-translator-providers>`
286287

287288
* `trusted_headers`_
288289
* `trusted_hosts`_
@@ -2404,6 +2405,19 @@ default_path
24042405
This option allows to define the path where the application translations files
24052406
are stored.
24062407

2408+
.. _reference-translator-providers:
2409+
2410+
providers
2411+
.........
2412+
2413+
**type**: ``array`` **default**: ``[]``
2414+
2415+
This option allows you to enable translation providers to push and pull your translations to third party providers.
2416+
2417+
.. seealso::
2418+
2419+
For more information about how to configure providers, see :ref:`translation-providers`.
2420+
24072421
property_access
24082422
~~~~~~~~~~~~~~~
24092423

‎translation.rst

Lines changed: 152 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -586,6 +586,158 @@ if you're generating translations with specialized programs or teams.
586586
:class:`Symfony\\Component\\Translation\\Loader\\LoaderInterface` interface.
587587
See the :ref:`dic-tags-translation-loader` tag for more information.
588588

589+
.. _translation-providers:
590+
591+
Translation Providers
592+
---------------------
593+
594+
.. versionadded:: 5.3
595+
596+
The "Translation Providers" feature was introduced in Symfony 5.3 as an
597+
:doc:`experimental feature </contributing/code/experimental>`.
598+
599+
The translation component can push and pull translations to third party providers (e.g. Crowdin or PoEditor).
600+
601+
Installing and configuring a 3rd Party Provider
602+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
603+
604+
Instead of editing your translation files as code, you can push them to one of the supported third-party providers.
605+
This will make the translations edition easier for you or your translators.
606+
607+
==================== ===========================================================
608+
Service Install with
609+
==================== ===========================================================
610+
Crowdin ``composer require symfony/crowdin-translation-provider``
611+
Loco (localise.biz) ``composer require symfony/loco-translation-provider``
612+
Lokalise ``composer require symfony/lokalise-translation-provider``
613+
PoEditor ``composer require symfony/po-editor-translation-provider``
614+
==================== ===========================================================
615+
616+
Each library includes a :ref:`Symfony Flex recipe <symfony-flex>` that will add
617+
a configuration example to your ``.env`` file. For example, suppose you want to
618+
use Loco. First, install it:
619+
620+
.. code-block:: terminal
621+
622+
$ composer require symfony/loco-translation-provider
623+
624+
You'll now have a new line in your ``.env`` file that you can uncomment:
625+
626+
.. code-block:: env
627+
628+
# .env
629+
LOCO_DSN=loco://API_KEY@default
630+
631+
The ``LOCO_DSN`` isn't a *real* address: it's a convenient format that
632+
offloads most of the configuration work to translation. The ``loco`` scheme
633+
activates the Loco provider that you just installed, which knows all about
634+
how to push and pull translations via Loco. The *only* part you need to change is the
635+
``API_KEY`` placeholder.
636+
637+
This table shows the full list of available DSN formats for each third party provider:
638+
639+
===================== =================================================================
640+
Provider DSN
641+
===================== =================================================================
642+
Crowdin crowdin://PROJECT_ID:API_TOKEN@default?domain=ORGANIZATION_DOMAIN
643+
Loco (localise.biz) loco://API_KEY@default
644+
Lokalise lokalise://PROJECT_ID:API_KEY@default
645+
PoEditor poeditor://PROJECT_ID:API_KEY@default
646+
===================== =================================================================
647+
648+
To enable a translation provider, add the correct DSN in your ``.env`` file and
649+
configure the ``providers``:
650+
651+
.. configuration-block::
652+
653+
.. code-block:: yaml
654+
655+
# config/packages/translation.yaml
656+
framework:
657+
translator:
658+
providers:
659+
loco:
660+
dsn: '%env(LOCO_DSN)%'
661+
domains: ['messages']
662+
locales: ['en', 'fr']
663+
664+
.. code-block:: xml
665+
666+
<!-- config/packages/translation.xml -->
667+
<?xml version="1.0" encoding="UTF-8" ?>
668+
<container xmlns="http://symfony.com/schema/dic/services"
669+
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
670+
xmlns:framework="http://symfony.com/schema/dic/symfony"
671+
xsi:schemaLocation="http://symfony.com/schema/dic/services
672+
https://symfony.com/schema/dic/services/services-1.0.xsd
673+
http://symfony.com/schema/dic/symfony
674+
https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
675+
676+
<framework:config>
677+
<framework:translator>
678+
<framework:provider name="loco" dsn="%env(LOCO_DSN)%">
679+
<framework:domain>messages</framework:domain>
680+
<!-- ... -->
681+
<framework:locale>en</framework:locale>
682+
<framework:locale>fr</framework:locale>
683+
<!-- ... -->
684+
</framework:provider>
685+
</framework:translator>
686+
</framework:config>
687+
</container>
688+
689+
.. code-block:: php
690+
691+
# config/packages/translation.php
692+
$container->loadFromExtension('framework', [
693+
'translator' => [
694+
'providers' => [
695+
'loco' => [
696+
'dsn' => '%env(LOCO_DSN)%',
697+
'domains' => ['messages'],
698+
'locales' => ['en', 'fr'],
699+
],
700+
],
701+
],
702+
]);
703+
704+
Push and pull translations
705+
~~~~~~~~~~~~~~~~~~~~~~~~~~
706+
707+
To push your existing translations to your configured third party provider, you have to use the `translation:push` command:
708+
709+
.. code-block:: terminal
710+
711+
# push all local translations to the Loco provider for the locales and domains configured in config/packages/translation.yaml file
712+
# it will update existing translations already on the provider.
713+
$ php bin/console translation:push loco --force
714+
715+
# push new local translations to the Loco provider for the French locale and the validators domain.
716+
# it will **not** update existing translations already on the provider.
717+
$ php bin/console translation:push loco --locales fr --domain validators
718+
719+
# push new local translations and delete provider's translations that not exists anymore in local files for the French locale and the validators domain.
720+
# it will **not** update existing translations already on the provider.
721+
$ php bin/console translation:push loco --delete-missing --locales fr --domain validators
722+
723+
# check out the command help to see its options (format, domains, locales, etc.)
724+
$ php bin/console translation:push --help
725+
726+
To pull translations from a provider in your local files, you have to use the `translation:pull` command:
727+
728+
.. code-block:: terminal
729+
730+
# pull all provider's translations to local files for the locales and domains configured in config/packages/translation.yaml file
731+
# it will overwrite completely your local files.
732+
$ php bin/console translation:pull loco --force
733+
734+
# pull new translations from the Loco provider to local files for the French locale and the validators domain.
735+
# it will **not** overwrite your local files, only add new translations.
736+
$ php bin/console translation:pull loco --locales fr --domain validators
737+
738+
# check out the command help to see its options (format, domains, locales, intl-icu, etc.)
739+
$ php bin/console translation:pull --help
740+
589741
Handling the User's Locale
590742
--------------------------
591743

0 commit comments

Comments
 (0)