Main menu

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 Extension Symfony loader
XLIFF .xlf XliffFileLoader
YAML .yml YamlFileLoader
PHP .php PhpFileLoader

Specify 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

The Loco importers support most of Symfony's message dumper formats, but take particular note of the following:

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. 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.

Translation keys

It's advisable to index your messages by "translation keys" rather than by your source language translations. These keys will become asset IDs when you import a file into Loco.

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 index=id.

XLIFF attributes

Symfony's 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 resname attribute. 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.

XLIFF 2.0

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.