Loco support for Symfony message catalogues
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 from Loco to Symfony
The file types supported by Symfony's message loaders are generic 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=symfony when exporting your project via the API, or find the Symfony variant you need in the dropdown list when exporting from the Loco dashboard.
These variants are structured in a way that Symfony will load, and support the following features:
- Loco plurals will export to Symfony's special plural syntax;
- Translations are indexed by asset ID by default, not by source text;
- Dot-delimited keys are nested in Yaml and PHP files for readability;
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 from Symfony to Loco
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. Symfony also supports custom plural rules (such as intervals) which Loco won't understand.
If your messages include pluralised strings, there are only two safe approaches:
- Manage "standard rules" inside Loco and avoid re-importing files from Symfony;
- Don't use Loco's plural features. Simply edit your pluralised strings in the raw syntax.
When importing translation files via the Loco dashboard make sure you select "Source: Asset IDs" from the importer dropdown list. This will prevent Loco from replacing your source language translations with your translation keys.
The same can be achieved via the API by specifying
XliffFileDumper populates both the
resname attribute and the
<source> element with each translation key.
Loco is happy with this, but take care if you're creating XLIFF files manually.
If you're importing "hand made" XLIFF files into Loco, make sure your files hold the translation key in the
Loco will look for the
resname attribute first, but if it's empty it will fallback on the
id attribute not the source element.
Typically the XLIFF
<source> element is for holding source language translations, not unique identifiers.
Loco supports the import and export of XLIFF 2.0, but our specific Symfony export format is XLIFF 1.2. This is still the default within Symfony and we recommend you stick to it. Importing XLIFF 2.0 files generated by Symfony may produce unexpected results.
See additional notes on importing XLIFF into Loco.