Main menu

Uniquely identifying assets

Every translatable asset in your Loco project has a unique key, which in Loco terminology is an Asset ID. You may have specific ideas about how you want to deal with identifiers, or you may not be concerned with them at all. Loco aims to facilitate whichever way of working you prefer.

Not using IDs? Your platform may not need language-agnostic keys at all. The source language text may be the only unique key you need. See identifying assets by source text if you're working without IDs.

Managing asset IDs

Loco is platform agnostic, so any style of identifier can be supported within reasonable limits. There are several ways to assign your IDs when you add assets to your dashboard:

  1. Add your assets manually via the UI and fill out the "Asset ID" field.
  2. Import assets from file and specify that source keys are IDs.
  3. Post your assets to the API and specify the "id" parameter.

If you add an asset without specifying an ID, one will be generated for you. You can change IDs at any time via the asset properties, but be aware that changing IDs can affect the matching of assets during future import operations.

Importing IDs from file

When importing translations you must tell Loco that your file is indexed by Asset IDs. This ensures that they are not treated as source text and will be imported exactly as you expect. Consider a JSON file that looks like this:

{"Foo":"Bar"}

Loco has no way of knowing that "Foo" is an ID and "Bar" is an English word. (Perhaps "Foo" is English and "Bar" is French). By telling Loco that "source keys are IDs" it will import it as you expect and your ID will be imported as "Foo".

See more about how language mapping affects the import process.

Exporting IDs to file

When exporting translations you can specify that the file is indexed by ID. This is the default for most platforms, but you can specify it for any file format. By exporting by ID you can guarantee that every string in your file is unique.

  • Invalid IDs
    Loco attempts to export Asset IDs exactly as you entered them, but there are some cases where specific export formats require some modification. For example: "foo-bar" would be an invalid Java variable so the Android XML exporter would change it to "foo_bar".

Duplicate ID handling

Every asset ID in your project is guaranteed to be unique. Loco won't let you add a new asset with a duplicate ID, but be careful when importing files, because Loco has no way of knowing when an existing ID is an accidental duplicate. Importing multiple assets with the same ID can produce unexpected results.

  • Context
    Loco provides a context field to disambiguate identical source strings, but this does not affect Asset IDs. It's not possible to have two assets with the same ID in the same project, regardless of the context setting.

Key folding

If you import a nested structure from JSON, PHP or YAML, the object keys will be imported as dot-delimited IDs. For example, the structure { "foo": { "bar": "Baz" } } would produce the key-folded ID "foo.bar".

The reverse happens when you export an ID containing a dot separator. This only applies to file formats that support object notation and can be disabled by passing the no-folding option to the export API.

Asset ID limitations

The rules for unique asset IDs are as follows:

  1. They cannot be empty strings.
  2. They cannot contain line breaks.
  3. They must be below 1,000 bytes in length.
  4. They must be unique within the same project.

Loco will allow any other format of ID you provide, but we recommended you stick to the printable ASCII range and avoid whitespace. If your IDs look like readable text then you're probably working without IDs and may be able to ignore asset IDs completely.

Automatic ID generation

There are two situations where Loco will automatically generate an Asset ID for you:

  1. Adding an asset manually and leaving the ID field empty;
  2. Importing assets from a file indexed by source text rather than by ID.

In these situations Loco will generate an ID from the available source text. For example: the text "Hello World!" will be given the ID "Hello-World", but if you'd prefer "HELLO_WORLD" or "hello.world" you can customize the format in your project's developer settings.

See also