Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Appearance settings

Commit 5d3ef38

Browse filesBrowse files
committed
Introduce Translation Providers
1 parent d7d3f7c commit 5d3ef38
Copy full SHA for 5d3ef38

File tree

2 files changed

+166
-0
lines changed
Filter options

2 files changed

+166
-0
lines changed

‎reference/configuration/framework.rst

Copy file name to clipboardExpand all lines: reference/configuration/framework.rst
+14Lines 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

Copy file name to clipboardExpand all lines: translation.rst
+152Lines 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 (0)
Morty Proxy This is a proxified and sanitized view of the page, visit original site.