Installation

Before you start, make sure you have StimulusBundle configured in your app.

Install this bundle using Composer and Symfony Flex:

1

$ composer require symfony/ux-translator

If you're using WebpackEncore, install your assets and restart Encore (not needed if you're using AssetMapper):

1
2
3
4
5
6

$ npm install --force
$ npm run watch

# or use yarn
$ yarn install --force
$ yarn watch

After installing the bundle, the following file should be created, thanks to the Symfony Flex recipe:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

// assets/translator.js

/*
 * This file is part of the Symfony UX Translator package.
 *
 * If folder "../var/translations" does not exist, or some translations are missing,
 * you must warmup your Symfony cache to refresh JavaScript translations.
 *
 * If you use TypeScript, you can rename this file to "translator.ts" to take advantage of types checking.
 */

import { trans, getLocale, setLocale, setLocaleFallbacks } from '@symfony/ux-translator';
import { localeFallbacks } from '../var/translations/configuration';

setLocaleFallbacks(localeFallbacks);

export { trans }
export * from '../var/translations';

Usage

When warming up the Symfony cache, all of your translations will be dumped as JavaScript into the var/translations/ directory. For a better developer experience, TypeScript types definitions are also generated aside those JavaScript files.

Then, you will be able to import those JavaScript translations in your assets. Don't worry about your final bundle size, only the translations you use will be included in your final bundle, thanks to the tree shaking.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

// assets/my_file.js

import {
    trans,
    TRANSLATION_SIMPLE,
    TRANSLATION_WITH_PARAMETERS,
    TRANSLATION_MULTI_DOMAINS,
    TRANSLATION_MULTI_LOCALES,
} from './translator';

// No parameters, uses the default domain ("messages") and the default locale
trans(TRANSLATION_SIMPLE);

// Two parameters "count" and "foo", uses the default domain ("messages") and the default locale
trans(TRANSLATION_WITH_PARAMETERS, { count: 123, foo: 'bar' });

// No parameters, uses the default domain ("messages") and the default locale
trans(TRANSLATION_MULTI_DOMAINS);
// Same as above, but uses the "domain2" domain
trans(TRANSLATION_MULTI_DOMAINS, {}, 'domain2');
// Same as above, but uses the "domain3" domain
trans(TRANSLATION_MULTI_DOMAINS, {}, 'domain3');

// No parameters, uses the default domain ("messages") and the default locale
trans(TRANSLATION_MULTI_LOCALES);
// Same as above, but uses the "fr" locale
trans(TRANSLATION_MULTI_LOCALES, {}, 'messages', 'fr');
// Same as above, but uses the "it" locale
trans(TRANSLATION_MULTI_LOCALES, {}, 'messages', 'it');

Using with AssetMapper

Using this library with AssetMapper is possible, but is currently experimental and may not be ready yet for production.

When installing with AssetMapper, Flex will add a few new items to your importmap.php file. 2 of the new items are:

1
2
3
4
5
6

'@app/translations' => [
    'path' => 'var/translations/index.js',
],
'@app/translations/configuration' => [
    'path' => 'var/translations/configuration.js',
],

These are then imported in your assets/translator.js file. This setup is very similar to working with WebpackEncore. However, the var/translations/index.js file contains every translation in your app, which is not ideal for production and may even leak translations only meant for admin areas. Encore solves this via tree-shaking, but the AssetMapper component does not. There is not, yet, a way to solve this properly with the AssetMapper component.

Backward Compatibility promise

This bundle aims at following the same Backward Compatibility promise as the Symfony framework: https://symfony.com/doc/current/contributing/code/bc.html