Translations
Warning: You are browsing the documentation for Symfony 4.x, which is no longer maintained.
Read the updated version of this page for Symfony 7.1 (the current stable version).
The term "internationalization" (often abbreviated i18n) refers to the process of abstracting strings and other locale-specific pieces out of your application into a layer where they can be translated and converted based on the user's locale (i.e. language and country). For text, this means wrapping each with a function capable of translating the text (or "message") into the language of the user:
1 2 3 4 5 6
// text will *always* print out in English
echo 'Hello World';
// text can be translated into the end-user's language or
// default to English
echo $translator->trans('Hello World');
Note
The term locale refers roughly to the user's language and country. It
can be any string that your application uses to manage translations and
other format differences (e.g. currency format). The ISO 639-1
language code, an underscore (_
), then the ISO 3166-1 alpha-2
country code (e.g. fr_FR
for French/France) is recommended.
The translation process has several steps:
- Enable and configure Symfony's translation service;
- Abstract strings (i.e. "messages") by wrapping them in calls to the
Translator
("Translations"); - Create translation resources/files for each supported locale that translate each message in the application;
- Determine, set and manage the user's locale for the request and optionally on the user's entire session.
Installation
First, run this command to install the translator before using it:
1
$ composer require symfony/translation
Configuration
The previous command creates an initial config file where you can define the default locale of the application and the directory where the translation files are located:
1 2 3 4 5
# config/packages/translation.yaml
framework:
default_locale: 'en'
translator:
default_path: '%kernel.project_dir%/translations'
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
<!-- 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 default-locale="en">
<framework:translator>
<framework:default-path>'%kernel.project_dir%/translations'</framework:default-path>
<!-- ... -->
</framework:translator>
</framework:config>
</container>
1 2 3 4 5 6
// config/packages/translation.php
$container->loadFromExtension('framework', [
'default_locale' => 'en',
'translator' => ['default_path' => '%kernel.project_dir%/translations'],
// ...
]);
The locale used in translations is the one stored on the request. This is
typically set via a _locale
attribute on your routes (see How to Work with the User's Locale).
Basic Translation
Translation of text is done through the translator
service
(Translator). To translate a block
of text (called a message), use the
trans() method. Suppose,
for example, that you're translating a static message from inside a controller:
1 2 3 4 5 6 7 8 9
// ...
use Symfony\Contracts\Translation\TranslatorInterface;
public function index(TranslatorInterface $translator)
{
$translated = $translator->trans('Symfony is great');
// ...
}
When this code is run, Symfony will attempt to translate the message
"Symfony is great" based on the locale
of the user. For this to work,
you need to tell Symfony how to translate the message via a "translation
resource", which is usually a file that contains a collection of translations
for a given locale. This "dictionary" of translations can be created in several
different formats:
1 2
# translations/messages.fr.yaml
Symfony is great: J'aime Symfony
1 2 3 4 5 6 7 8 9 10 11 12
<!-- translations/messages.fr.xlf -->
<?xml version="1.0" encoding="UTF-8" ?>
<xliff version="1.2" xmlns="urn:oasis:names:tc:xliff:document:1.2">
<file source-language="en" datatype="plaintext" original="file.ext">
<body>
<trans-unit id="symfony_is_great">
<source>Symfony is great</source>
<target>J'aime Symfony</target>
</trans-unit>
</body>
</file>
</xliff>
1 2 3 4
// translations/messages.fr.php
return [
'Symfony is great' => "J'aime Symfony",
];
For information on where these files should be located, see Translations.
Now, if the language of the user's locale is French (e.g. fr_FR
or fr_BE
),
the message will be translated into J'aime Symfony
. You can also translate
the message inside your templates.
Using Real or Keyword Messages
This example illustrates the two different philosophies when creating messages to be translated:
1 2 3
$translator->trans('Symfony is great');
$translator->trans('symfony.great');
In the first method, messages are written in the language of the default locale (English in this case). That message is then used as the "id" when creating translations.
In the second method, messages are actually "keywords" that convey the
idea of the message. The keyword message is then used as the "id" for
any translations. In this case, translations must be made for the default
locale (i.e. to translate symfony.great
to Symfony is great
).
The second method is handy because the message key won't need to be changed in every translation file if you decide that the message should actually read "Symfony is really great" in the default locale.
The choice of which method to use is entirely up to you, but the "keyword" format is often recommended for multi-language applications, whereas for shared bundles that contain translation resources we recommend the real message, so your application can choose to disable the translator layer and you will see a readable message.
Additionally, the php
and yaml
file formats support nested ids to
avoid repeating yourself if you use keywords instead of real text for your
ids:
1 2 3 4 5 6 7 8 9 10 11 12
symfony:
is:
# id is symfony.is.great
great: Symfony is great
# id is symfony.is.amazing
amazing: Symfony is amazing
has:
# id is symfony.has.bundles
bundles: Symfony has bundles
user:
# id is user.login
login: Login
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18
[
'symfony' => [
'is' => [
// id is symfony.is.great
'great' => 'Symfony is great',
// id is symfony.is.amazing
'amazing' => 'Symfony is amazing',
],
'has' => [
// id is symfony.has.bundles
'bundles' => 'Symfony has bundles',
],
],
'user' => [
// id is user.login
'login' => 'Login',
],
];
The Translation Process
To actually translate the message, Symfony uses the following process when
using the trans()
method:
- The
locale
of the current user, which is stored on the request is determined; - A catalog (e.g. big collection) of translated messages is loaded from translation
resources defined for the
locale
(e.g.fr_FR
). Messages from the fallback locale are also loaded and added to the catalog if they don't already exist. The end result is a large "dictionary" of translations. This catalog is cached in production to minimize performance impact. - If the message is located in the catalog, the translation is returned. If not, the translator returns the original message.
Tip
When translating strings that are not in the default domain (messages
),
you must specify the domain as the third argument of trans()
:
1
$translator->trans('Symfony is great', [], 'admin');
Message Format
Sometimes, a message containing a variable needs to be translated:
1 2
// ...
$translated = $translator->trans('Hello '.$name);
However, creating a translation for this string is impossible since the translator will try to look up the message including the variable portions (e.g. "Hello Ryan" or "Hello Fabien").
Another complication is when you have translations that may or may not be plural, based on some variable:
1 2
There is one apple.
There are 5 apples.
To manage these situations, Symfony follows the ICU MessageFormat syntax by using PHP's MessageFormatter class. Read more about this in How to Translate Messages using the ICU MessageFormat.
4.2
Support for ICU MessageFormat was introduced in Symfony 4.2. Prior to this, pluralization was managed by the transChoice() method.
Translations in Templates
Most of the time, translation occurs in templates. Symfony provides native support for both Twig and PHP templates.
Using Twig Tags
Symfony provides specialized Twig tags (trans
and transchoice
) to
help with message translation of static blocks of text:
1 2 3 4 5
{% trans %}Hello %name%{% endtrans %}
{% transchoice count %}
{0} There are no apples|{1} There is one apple|]1,Inf[ There are %count% apples
{% endtranschoice %}
The transchoice
tag automatically gets the %count%
variable from
the current context and passes it to the translator. This mechanism only
works when you use a placeholder following the %var%
pattern.
4.2
The transchoice
tag is deprecated since Symfony 4.2 and will be
removed in 5.0. Use the ICU MessageFormat with
the trans
tag instead.
Caution
The %var%
notation of placeholders is required when translating in
Twig templates using the tag.
Tip
If you need to use the percent character (%
) in a string, escape it by
doubling it: {% trans %}Percent: %percent%%%{% endtrans %}
You can also specify the message domain and pass some additional variables:
1 2 3 4 5 6 7
{% trans with {'%name%': 'Fabien'} from 'app' %}Hello %name%{% endtrans %}
{% trans with {'%name%': 'Fabien'} from 'app' into 'fr' %}Hello %name%{% endtrans %}
{% transchoice count with {'%name%': 'Fabien'} from 'app' %}
{0} %name%, there are no apples|{1} %name%, there is one apple|]1,Inf[ %name%, there are %count% apples
{% endtranschoice %}
Using Twig Filters
The trans
and transchoice
filters can be used to translate variable
texts and complex expressions:
1 2 3 4 5 6 7
{{ message|trans }}
{{ message|transchoice(5) }}
{{ message|trans({'%name%': 'Fabien'}, 'app') }}
{{ message|transchoice(5, {'%name%': 'Fabien'}, 'app') }}
4.2
The transchoice
filter is deprecated since Symfony 4.2 and will be
removed in 5.0. Use the ICU MessageFormat with
the trans
filter instead.
Tip
Using the translation tags or filters have the same effect, but with
one subtle difference: automatic output escaping is only applied to
translations using a filter. In other words, if you need to be sure
that your translated message is not output escaped, you must apply
the raw
filter after the translation filter:
1 2 3 4 5 6 7 8 9 10
{# text translated between tags is never escaped #}
{% trans %}
<h3>foo</h3>
{% endtrans %}
{% set message = '<h3>foo</h3>' %}
{# strings and variables translated via a filter are escaped by default #}
{{ message|trans|raw }}
{{ '<h3>bar</h3>'|trans|raw }}
Tip
You can set the translation domain for an entire Twig template with a single tag:
1
{% trans_default_domain 'app' %}
Note that this only influences the current template, not any "included" template (in order to avoid side effects).
PHP Templates
The translator service is accessible in PHP templates through the
translator
helper:
1 2 3 4 5 6 7
<?= $view['translator']->trans('Symfony is great') ?>
<?= $view['translator']->transChoice(
'{0} There are no apples|{1} There is one apple|]1,Inf[ There are %count% apples',
10,
['%count%' => 10]
) ?>
Forcing the Translator Locale
When translating a message, the translator uses the specified locale or the
fallback
locale if necessary. You can also manually specify the locale to
use for translation:
1 2 3 4 5 6
$translator->trans(
'Symfony is great',
[],
'messages',
'fr_FR'
);
Extracting Translation Contents and Updating Catalogs Automatically
The most time-consuming tasks when translating an application is to extract all
the template contents to be translated and to keep all the translation files in
sync. Symfony includes a command called translation:update
that helps you
with these tasks:
1 2 3 4 5 6 7 8
# shows all the messages that should be translated for the French language
$ php bin/console translation:update --dump-messages fr
# updates the French translation files with the missing strings for that locale
$ php bin/console translation:update --force fr
# check out the command help to see its options (prefix, output format, domain, sorting, etc.)
$ php bin/console translation:update --help
The translation:update
command looks for missing translations in:
- Templates stored in the
templates/
directory (or any other directory defined in the twig.default_path and twig.paths config options); - Any PHP file/class that injects or autowires
the
translator
service and makes calls to thetrans()
method.
4.3
The extraction of missing translation strings from PHP files was introduced in Symfony 4.3.
Translation Resource/File Names and Locations
Symfony looks for message files (i.e. translations) in the following default locations:
- the
translations/
directory (at the root of the project); - the
src/Resources/<bundle name>/translations/
directory; - the
Resources/translations/
directory inside of any bundle.
4.2
Using the src/Resources/<bundle name>/translations/
directory to store
translations was deprecated in Symfony 4.2. Use instead the directory
defined in the default_path
option (which is translations/
by default).
The locations are listed here with the highest priority first. That is, you can override the translation messages of a bundle in any of the top two directories.
The override mechanism works at a key level: only the overridden keys need to be listed in a higher priority message file. When a key is not found in a message file, the translator will automatically fall back to the lower priority message files.
The filename of the translation files is also important: each message file
must be named according to the following path: domain.locale.loader
:
- domain: Domains are a way to organize messages into groups. Unless
parts of the application are explicitly separated from each other, it is
recommended to only use the default
messages
domain (e.g.messages.en.yaml
). - locale: The locale that the translations are for (e.g.
en_GB
,en
, etc); - loader: How Symfony should load and parse the file (e.g.
xlf
,php
,yaml
, etc).
The loader can be the name of any registered loader. By default, Symfony provides many loaders:
.yaml
: YAML file.xlf
: XLIFF file;.php
: Returning a PHP array;.csv
: CSV file;.json
: JSON file;.ini
: INI file;.dat
,.res
: ICU resource bundle;.mo
: Machine object format;.po
: Portable object format;.qt
: QT Translations XML file;
The choice of which loader to use is entirely up to you and is a matter of taste. The recommended option is to use YAML for simple projects and use XLIFF if you're generating translations with specialized programs or teams.
Caution
Each time you create a new message catalog (or install a bundle that includes a translation catalog), be sure to clear your cache so that Symfony can discover the new translation resources:
1
$ php bin/console cache:clear
Note
You can add other directories with the paths option in the configuration:
1 2 3 4 5
# config/packages/translation.yaml
framework:
translator:
paths:
- '%kernel.project_dir%/custom/path/to/translations'
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
<!-- config/packages/translation.xml -->
<?xml version="1.0" encoding="UTF-8" ?>
<container xmlns="http://symfony.com/schema/dic/services"
xmlns:framework="http://symfony.com/schema/dic/symfony"
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
http://symfony.com/schema/dic/symfony
https://symfony.com/schema/dic/symfony/symfony-1.0.xsd">
<framework:config>
<framework:translator>
<framework:path>%kernel.project_dir%/custom/path/to/translations</framework:path>
</framework:translator>
</framework:config>
</container>
1 2 3 4 5 6 7 8
// config/packages/translation.php
$container->loadFromExtension('framework', [
'translator' => [
'paths' => [
'%kernel.project_dir%/custom/path/to/translations',
],
],
]);
Note
You can also store translations in a database, or any other storage by providing a custom class implementing the LoaderInterface interface. See the Built-in Symfony Service Tags tag for more information.
4.3
Starting from Symfony 4.3, when you create a new translation file (or
install a bundle that includes translation files), you don't have to clear
the cache with the command php bin/console cache:clear
as you had to do
in previous Symfony versions.
Handling the User's Locale
Translating happens based on the user's locale. Read How to Work with the User's Locale to learn more about how to handle it.
Fallback Translation Locales
Imagine that the user's locale is es_AR
and that you're translating the
key Symfony is great
. To find the Spanish translation, Symfony actually
checks translation resources for several locales:
- First, Symfony looks for the translation in a
es_AR
(Argentinean Spanish) translation resource (e.g.messages.es_AR.yaml
); - If it wasn't found, Symfony looks for the translation in the
parent locale, which is automatically defined only for some locales. In
this example, the parent locale is
es_419
(Latin American Spanish); - If it wasn't found, Symfony looks for the translation in a
es
(Spanish) translation resource (e.g.messages.es.yaml
); If the translation still isn't found, Symfony uses the
fallbacks
option, which can be configured as follows:1 2 3 4 5
# config/packages/translation.yaml framework: translator: fallbacks: ['en'] # ...
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17
<!-- 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:translator> <framework:fallback>en</framework:fallback> <!-- ... --> </framework:translator> </framework:config> </container>
1 2 3 4 5
// config/packages/translation.php $container->loadFromExtension('framework', [ 'translator' => ['fallbacks' => ['en']], // ... ]);
4.4
In Symfony versions before 4.4, the fallbacks
option was initialized to
en
(English) when not configured explicitly. Starting from Symfony 4.4,
this option is initialized to the same value as the default_locale
option.
Note
When Symfony can't find a translation in the given locale, it will add the missing translation to the log file. For details, see Framework Configuration Reference (FrameworkBundle).
Translating Database Content
The translation of database content should be handled by Doctrine through the Translatable Extension or the Translatable Behavior (PHP 5.4+). For more information, see the documentation for these libraries.
Debugging Translations
When you work with many translation messages in different languages, it can be hard to keep track which translations are missing and which are not used anymore. Read How to Find Missing or Unused Translation Messages to find out how to identify these messages.
Summary
With the Symfony Translation component, creating an internationalized application no longer needs to be a painful process and boils down to these steps:
- Abstract messages in your application by wrapping each in the trans() method;
- Translate each message into multiple locales by creating translation message files. Symfony discovers and processes each file because its name follows a specific convention;
- Manage the user's locale, which is stored on the request, but can also be set on the user's session.