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|
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
target-language attributes should match your Loco project locales as closely as possible.
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
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|
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'
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
Be aware that the
locale=target option is relatively new. Many libraries will specify
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.