The Translation Component

    Note

    If you install this component outside of a Symfony application, you mustrequire the file in your code to enable the classautoloading mechanism provided by Composer. Readthis article for more details.

    This article explains how to use the Translation features as an independentcomponent in any PHP application. Read the article tolearn about how to internationalize and manage the user locale in Symfonyapplications.

    Constructing the Translator

    The main access point of the Translation component is. Before you can use it,you need to configure it and load the messages to translate (called messagecatalogs).

    The constructor of the Translator class needs one argument: The locale:

    1. use Symfony\Component\Translation\Translator;
    2.  
    3. $translator = new Translator('fr_FR');

    Note

    The locale set here is the default locale to use. You can override thislocale when translating strings.

    The term locale refers roughly to the user's language and country. Itcan be any string that your application uses to manage translations andother format differences (e.g. currency format). The ISO 639-1language code, an underscore (), then the _country code (e.g. fr_FR for French/France) is recommended.

    The messages are stored in message catalogs inside the Translatorclass. A message catalog is like a dictionary of translations for a specificlocale.

    The Translation component uses Loader classes to load catalogs. You can loadmultiple resources for the same locale, which will then be combined into onecatalog.

    The component comes with some default Loaders and you can create your ownLoader too. The default loaders are:

    • ArrayLoader - to loadcatalogs from PHP arrays.
    • - to loadcatalogs from resource bundles.
    • IcuResFileLoader - to loadcatalogs from resource bundles.
    • - to loadcatalogs from ini files.
    • MoFileLoader - to loadcatalogs from gettext files.
    • - to loadcatalogs from PHP files.
    • - to loadcatalogs from gettext files.
    • QtFileLoader - to loadcatalogs from QT XML files.
    • - to loadcatalogs from Xliff files.
    • JsonFileLoader - to loadcatalogs from JSON files.
    • - to loadcatalogs from Yaml files (requires the Yaml component).All file loaders require the .

    You can also create your own Loader,in case the format is not already supported by one of the default loaders.

    At first, you should add one or more loaders to the Translator:

    The first argument is the name to which you can refer the loader in thetranslator and the second argument is an instance of the loader itself. Afterthis, you can add your resources using the correct loader.

    Loading Messages with the ArrayLoader

    1. // ...
    2. $translator->addResource('array', [
    3.     'Hello World!' => 'Bonjour',
    4. ], 'fr_FR');

    Loading Messages with the File Loaders

    If you use one of the file loaders, you should also use the addResource()method. The only difference is that you should put the file name to the resourcefile as the second argument, instead of an array:

    To actually translate the message, the Translator uses the following process:

    • A catalog of translated messages is loaded from translation resources definedfor the locale (e.g. fr_FR). Messages from the are also loaded and added to thecatalog, if they don't already exist. The end result is a large "dictionary"of translations;

    If the message is not located in the catalog of the specific locale, thetranslator will look into the catalog of one or more fallback locales. Forexample, assume you're trying to translate into the locale:

    • First, the translator looks for the translation in the es_AR(Argentinean Spanish) locale;
    • If it wasn't found, the translator looks for the translation in the parentlocale, which is automatically defined only for some locales. In thisexample, the parent locale is es_419 (Latin American Spanish);
    • If it wasn't found, the translator looks for the translation in the es(Spanish) locale;
    • If the translation still isn't found, the translator uses the one or morefallback locales set explicitly on the translator.For (3), the fallback locales can be set by callingsetFallbackLocales():
    1. // ...
    2. $translator->setFallbackLocales(['en']);

    Using Message Domains

    As you've seen, message files are organized into the different locales thatthey translate. The message files can also be organized further into "domains".

    The domain is specified in the fourth argument of the addResource()method. The default domain is messages. For example, suppose that, fororganization, translations were split into three different domains:messages, admin and navigation. The French translation would beloaded like this:

    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');

    Read how to use the Translation component in Using the Translator.

    Learn More