Skip to content

Commit 485ffbd

Browse files
welcoMatticwelcoMattic
committed
Introduce Translation Providers
1 parent d7d3f7c commit 485ffbd

File tree

2 files changed

+165
-0
lines changed

2 files changed

+165
-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: 151 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -586,6 +586,157 @@ 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: '%locales%'
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+
<!-- ... -->
683+
</framework:provider>
684+
</framework:translator>
685+
</framework:config>
686+
</container>
687+
688+
.. code-block:: php
689+
690+
# config/packages/translation.php
691+
$container->loadFromExtension('framework', [
692+
'translator' => [
693+
'providers' => [
694+
'loco' => [
695+
'dsn' => '%env(LOCO_DSN)%',
696+
'domains' => ['messages'],
697+
'locales' => '%locales%',
698+
],
699+
],
700+
],
701+
]);
702+
703+
Push and pull translations
704+
~~~~~~~~~~~~~~~~~~~~~~~~~~
705+
706+
To push your existing translations to your configured third party provider, you have to use the `translation:push` command:
707+
708+
.. code-block:: terminal
709+
710+
# push all local translations to the Loco provider for the locales and domains configured in config/packages/translation.yaml file
711+
# it will update existing translations already on the provider.
712+
$ php bin/console translation:push loco --force
713+
714+
# push new local translations to the Loco provider for the French locale and the validators domain.
715+
# it will **not** update existing translations already on the provider.
716+
$ php bin/console translation:push loco --locales fr --domain validators
717+
718+
# push new local translations and delete provider's translations that not exists anymore in local files for the French locale and the validators domain.
719+
# it will **not** update existing translations already on the provider.
720+
$ php bin/console translation:push loco --delete-missing --locales fr --domain validators
721+
722+
# check out the command help to see its options (format, domains, locales, etc.)
723+
$ php bin/console translation:push --help
724+
725+
To pull translations from a provider in your local files, you have to use the `translation:pull` command:
726+
727+
.. code-block:: terminal
728+
729+
# pull all provider's translations to local files for the locales and domains configured in config/packages/translation.yaml file
730+
# it will overwrite completely your local files.
731+
$ php bin/console translation:pull loco --force
732+
733+
# pull new translations from the Loco provider to local files for the French locale and the validators domain.
734+
# it will **not** overwrite your local files, only add new translations.
735+
$ php bin/console translation:pull loco --locales fr --domain validators
736+
737+
# check out the command help to see its options (format, domains, locales, intl-icu, etc.)
738+
$ php bin/console translation:pull --help
739+
589740
Handling the User's Locale
590741
--------------------------
591742

0 commit comments

Comments
 (0)