Extracting locales

To ensure your file is imported correctly you need to tell Loco what your file contains and what languages you want to extract from it. If you're not sure which options to select from the dashboard importer, here are some examples of common cases:

Mapping one language to another

Files will often map your source language to a target language. Depending on the file type, it may look something like this where the key is English and the value is Spanish:

"Hello World" : "Hola Mundo"

If your file looks like this you would select "Source/keys: English" and "Target/translations: Spanish" to import translations in both languages. Once imported to Loco you would have one asset with two translations.

To use this mapping via the import API, you can specify index=text. Note that it is the default for some formats, such as PO files.

Mapping IDs to translations

Some files may not be indexed by source language translations. They may instead use a generic key. This example shows the source language is actually the target:

"greeting" : "Hello World"

If your file looks like this you would select "Source/keys: Keys are asset IDs" and "Target/translations: English". The important difference here is that "greeting" will not be imported as a translation, it will become your Loco asset ID.

To use this mapping via the import API, you can specify index=id. Note that it is the default for most file formats, including Yaml as per this example.

No translations

You may be importing a template file that hasn't been translated at all. For example, it might contain just empty strings like this:

"Hello World" : ""

If your file looks like this you would select "Source/keys: English" and "Target/translations: None (source only)". Don't specify a target unless you want Loco to import empty strings as they would overwrite any existing translations.

Complex structures

Some file formats are more complex than just key/value pairs. The most common of these formats is XLIFF which defines unique IDs in addition to multiple language declarations. Here's a simple snippet to demonstrate the concept:

<trans-unit id="greeting">
    <source>Hello World</source>
    <target>Hola Mundo</target>
</trans-unit>

These formats should normally be considered to be indexed by ID as it's unlikely their unique identifiers are being used to contain full source text. To import this example from the user interface, you would select "Source/keys: Keys are asset IDs" and "Target/translations: Auto (detect languages)". The special "auto" option will extract all translations that can be matched to a project locale. That means you'll get English and Spanish in addition to your asset IDs in this example.

Symfony users should take particular note of how <source> elements are extracted. See Importing XLIFF files for detailed examples.

IDs vs source text

It's important to understand that in Loco terminology your source text is not an Asset ID, even if you're using it as a unique key:

• Tell the importer that your file is indexed by ID and Loco will import your IDs without change;
• Tell the importer that your file is indexed by text and Loco will generate an ID additionally.

These two import methods should not be used interchangeably. Choose the approach that's right for your platform and stick to it. See the developer guides to Asset IDs and identifying assets by source text.

Import merging

The Loco importer tries to match all entries in your file to assets already in your project. The following is what happens by default when you import a file at any time into your project:

• New assets: Unmatched entries will be added to your project;
• Existing assets: If an entry can be matched it will be updated in your project (assuming it's changed);
• Missing assets: Assets in your project that aren't in your file will just be ignored and remain in your project;
• Translation status: The first translation of an asset automatically becomes "translated". Updated translations keep their existing status.

A small number of formats can specify translation status within the file. For example a Gettext "fuzzy" entry will be flagged during a PO file import.

Optional settings

The default merging behaviour can be changed by altering the settings on the right-hand side of the import screen. Click the :cog icon: to change the following import settings:

• General
  Specify tags to be applied to all assets processed by the import.
  These options correspond to the tag-all and untag-all API parameters.

• Create (new assets: in file but not in project)
  This option tells the importer than any unmatched assets in your file are "new" and should be added to your Loco project.
  Disabling this is equivalent to specifying ignore-new via the API.

  • Tags specified here are only applied to assets when they're created for the first time.
    This corresponds to the tag-new API parameter.

  • Status specified here overrides the initial state of new translations, for example flagging them as "provisional" instead of "translated". This corresponds to the flag-new API parameter.

• Update (existing assets: in file and in project)
  This option tells the importer that any assets in your file that are already in your project may be modified during import.
  Disabling this is equivalent to specifying ignore-existing via the API.

  • Tags specified here are only applied to existing assets that are modified during the import.
    This corresponds to the tag-updated and untag-updated API parameters.

  • Status values specified here are applied to translations modified during import, depending on their existing status. This corresponds to the flag-updated API parameter, but allows more specific mapping rules.

  • Allow blanks means that existing translations may be overwritten by empty strings if they exist in your file. Disabling this is equivalent to specifying the ignore-blanks API parameter. Recommended if your file is partially translated.

• Delete (missing assets: in project, but not in file)
  Deselecting this option permanently deletes any asset in your project that isn't found in the file.
  Disabling this is equivalent to specifying delete-absent via the API.

  • Tags specified here are only applied to assets not present in the file.
    These options correspond to the tag-absent and untag-absent API parameters.

Important: Asset deletion is permanent. It's better to use tag-absent and review redundant assets for deletion after import.

File formats

Most language pack formats can be detected simply by their file extension, either because it's a reserved name (e.g. .strings,.plist) or because the file is able to declare its own schema (e.g. .xml,.xlf) or has a recognizable structure (e.g. some JSON schemas).

For file formats that Loco can't automatically detect, you can specify the format parameter via the Import API which is reciprocal to the export parameter of the same name. It's recommended to always specify this parameter when importing generic file formats like JSON.