Main menu

Support for Symfony message catalogues in Loco

As explained in its best practice guide, Symfony supports many translation files formats; most of which are also supported by Loco. XLIFF is the recommended format, but any of the formats listed below will work.

Exporting message catalogues from Loco

The file types supported by Symfony's message loaders are standard formats, but Symfony has some specific requirements for how they must be used. Loco offers three Symfony-specific variants for exporting the following file types:

Format Extension Symfony loader Symfony dumper
XLIFF .xlf XliffFileLoader XliffFileDumper
YAML .yml YamlFileLoader YamlFileDumper
PHP .php PhpFileLoader PhpFileDumper

Find the variant you need in the dropdown list when exporting from the Loco dashboard, or specify format=symfony when downloading files from the Export API. See more detailed API examples below.

The Symfony variants of these standard formats are structured in a way that Symfony will load. Avoid exporting other formats from Loco to Symfony. Many others might seem to work, but Symfony-specific features will be missing and you might get confusing results.

Importing message catalogues into Loco

Loco's import tools support most of Symfony's message dumper formats, but we recommend importing Yaml, PHP or XLIFF. Symfony recommends XLIFF as the format you should use for message catalogues, so it's the one we'll mainly discuss here.

Because Symfony message catalogues use translation keys make sure you select "Keys are asset IDs" from Loco's file import dropdown list. This prevents your source language translations becoming populated with your translation keys. The same can be achieved via the API by specifying index=id or simply leaving it out as shown in the examples below.

Unlike Yaml and PHP catalogues, XLIFF is an expressive XML schema that supports much more than simple key/value pairs. For detailed examples see importing XLIFF files, which includes a Symfony example.

Take particular note of the fact that XLIFF is self-describing. This means your source-language and target-language attributes should match your Loco project locales as closely as possible.

XLIFF versions

Loco supports the import and export of XLIFF 2.0, but our Symfony-specific export format is XLIFF 1.2. For that reason exporting XLIFF 1.2 is still recommended for getting your strings out of Loco. Exporting XLIFF 2.0 is possible by passing format=xlf2 to the API, but this will not give you a structure suitable for Symfony's XliffFileLoader.

Importing XLIFF 2.0 is supported however, because they are semantically equivalent as far as Loco needs them to be. In the pages of our guides you can translate XLIFF terminology as follows:

XLIFF 1.2 XLIFF 2.0
resname name
source-language srcLang
target-language trgLang

Plural rules

Messages using Symfony's plural syntax will not be converted to Loco plurals during import. Files exported from Symfony do not indicate whether a string is intended to be pluralised, so Loco will just import them as-is. That also means they'll be exported as-is, so this may be fine for your needs.

Loco also supports ICU plural syntax which Symfony is to adopt in place of the old syntax. We recommend you use this syntax in your Loco projects if you're working with a version of Symfony that supports it. See ICU support in Loco.

If you're using Loco's standard plural system you will find that Loco exports still compile them into Symfony plural syntax. This is a legacy feature that will eventually be removed, so we recommend against using it.

Finally an example

Supposing you've dumped two XLIFF files from Symfony; one for English and one for French. This is how we recommend you import them into Loco. Firstly ensure you've added French (fr) to your Loco project locales. Then import them using cURL as follows:

curl -u <your_key>: --data-binary @messages.en.xliff 'https://localise.biz/api/import/xliff?locale=target'
curl -u <your_key>: --data-binary @messages.fr.xliff 'https://localise.biz/api/import/xliff?locale=target'

The locale parameter is target in both cases. This pattern is explained in more detail in importing XLIFF files. It will succeed as long as the target-language attributes in your files match the locales in your Loco project.

At this point you can edit translations for both languages in the Loco dashboard. When you need to export them back to disk again, you can do so as follows:

curl -u <your_key>: 'https://localise.biz/api/export/locale/en.xlf?format=symfony' > Resources/messages.en.xlf
curl -u <your_key>: 'https://localise.biz/api/export/locale/fr.xlf?format=symfony' > Resources/messages.fr.xlf

Of course there are various tools to do this for you, but it's good to know what's going on under the hood. See our list of Loco client libraries (in particular the php-translation adapter).

Be aware that the locale=target option is relatively new. Many libraries will specify locale=en and locale=fr. This will be fine in most cases, but runs the risk of accidentally targeting the <source> elements if the file's language attributes are labelled wrongly.
See the detailed guide for this edge case.