Main menu

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: English" and "Target: 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: Asset IDs" and "Target: 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: English" and "Target: None". Don't specify a target unless you want Loco to import empty strings as they would overwrite any existing translations.

Multiple languages

Some file formats support more than two languages. If your file contains multiple languages its especially important to ensure your project locales correlate with your file. A good example of this situation is importing XLIFF files.

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

These two import methods are not compatible with one another. 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.

  • 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.
    These options correspond to the tag-updated and untag-updated API parameters.

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