Translation¶

The TranslationServiceProvider provides a service for translating your application into different languages.

Parameters¶

translator.domains (optional): A mapping of domains/locales/messages. This parameter contains the translation data for all languages and domains.
locale (optional): The locale for the translator. You will most likely want to set this based on some request parameter. Defaults to en.
locale_fallbacks (optional): Fallback locales for the translator. It will be used when the current locale has no messages set. Defaults to en.
translator.cache_dir (optional): Defines the cache directory if you want translations to be cached.

Services¶

translator: An instance of Translator, that is used for translation.
translator.loader: An instance of an implementation of the translation LoaderInterface, defaults to an ArrayLoader.
translator.message_selector: An instance of MessageSelector.

Registering¶

$app->register(new Mascot\Provider\LocaleServiceProvider());
$app->register(new Mascot\Provider\TranslationServiceProvider(), array(
    'locale_fallbacks' => array('en'),
));

Note

Add the Symfony Translation Component as a dependency:

composer require symfony/translation

Usage¶

The Translation provider provides a translator service and makes use of the translator.domains parameter:

$app['translator.domains'] = array(
    'messages' => array(
        'en' => array(
            'hello'     => 'Hello %name%',
            'goodbye'   => 'Goodbye %name%',
        ),
        'de' => array(
            'hello'     => 'Hallo %name%',
            'goodbye'   => 'Tschüss %name%',
        ),
        'fr' => array(
            'hello'     => 'Bonjour %name%',
            'goodbye'   => 'Au revoir %name%',
        ),
    ),
    'validators' => array(
        'fr' => array(
            'This value should be a valid number.' => 'Cette valeur doit être un nombre.',
        ),
    ),
);

$app->get('/{_locale}/{message}/{name}', function ($message, $name) use ($app) {
    return $app['translator']->trans($message, array('%name%' => $name));
});

The above example will result in following routes:

/en/hello/igor will return Hello igor.
/de/hello/igor will return Hallo igor.
/fr/hello/igor will return Bonjour igor.
/it/hello/igor will return Hello igor (because of the fallback).

Using Resources¶

When translations are stored in a file, you can load them as follows:

$app = new Application();

$app->register(new TranslationServiceProvider());
$app->extend('translator.resources', function ($resources, $app) {
    $resources = array_merge($resources, array(
        array('array', array('This value should be a valid number.' => 'Cette valeur doit être un nombre.'), 'fr', 'validators'),
    ));

    return $resources;
});

Traits¶

Mascot\Application\TranslationTrait adds the following shortcuts:

trans: Translates the given message.
transChoice: Translates the given choice message by choosing a translation according to a number.

$app->trans('Hello World');

$app->transChoice('Hello World');

Recipes¶

YAML-based language files¶

Having your translations in PHP files can be inconvenient. This recipe will show you how to load translations from external YAML files.

First, add the Symfony Config and Yaml components as dependencies:

composer require symfony/config symfony/yaml

Next, you have to create the language mappings in YAML files. A naming you can use is locales/en.yml. Just do the mapping in this file as follows:

hello: Hello %name%
goodbye: Goodbye %name%

Then, register the YamlFileLoader on the translator and add all your translation files:

use Symfony\Component\Translation\Loader\YamlFileLoader;

$app->extend('translator', function($translator, $app) {
    $translator->addLoader('yaml', new YamlFileLoader());

    $translator->addResource('yaml', __DIR__.'/locales/en.yml', 'en');
    $translator->addResource('yaml', __DIR__.'/locales/de.yml', 'de');
    $translator->addResource('yaml', __DIR__.'/locales/fr.yml', 'fr');

    return $translator;
});

XLIFF-based language files¶

Just as you would do with YAML translation files, you first need to add the Symfony Config component as a dependency (see above for details).

Then, similarly, create XLIFF files in your locales directory and add them to the translator:

$translator->addResource('xliff', __DIR__.'/locales/en.xlf', 'en');
$translator->addResource('xliff', __DIR__.'/locales/de.xlf', 'de');
$translator->addResource('xliff', __DIR__.'/locales/fr.xlf', 'fr');

Note

The XLIFF loader is already pre-configured by the extension.

Accessing translations in Twig templates¶

Once loaded, the translation service provider is available from within Twig templates when using the Twig bridge provided by Symfony (see TwigServiceProvider):

{{ 'translation_key'|trans }}
{{ 'translation_key'|transchoice }}
{% trans %}translation_key{% endtrans %}