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, which is the default for XLIFF, 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 defaults to XLIFF 1.2.
Exporting XLIFF 2.0 is possible by passing xlf-version=2 to the API, see exporting XLIFF files, which includes a Symfony example.
Importing XLIFF 2.0 is supported too, because they are semantically equivalent as far as their usage with Symfony goes. When reading our help pages be aware that XLIFF terminology is interchangeable as follows:
| XLIFF 1.2 | XLIFF 2.0 |
|---|---|
resname |
name |
source-language |
srcLang |
target-language |
trgLang |
Plural rules
Messages using Symfony's legacy 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 has adopted 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?format=symfony&locale=en'
curl -u <your_key>: --data-binary @messages.fr.xliff 'https://localise.biz/api/import/xliff?format=symfony&locale=fr'
You could also specify locale=target for both imports. These commands are explained in more detail in importing XLIFF files.
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).