Main menu

Asset IDs

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 should 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 will assume in this case (by default) that "Foo" is an ID and "Bar" is a word in your source language. It would have no way of knowing that "Foo" is actually source text, and "Bar" is a translation.

This is the default for JSON, but not for all formats, so it's good practice to tell Loco explicitly that keys are IDs. This way your files 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 you want a file indexed by ID. This is the default for most file formats (including JSON), but you can override the default behaviour for any 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 doesn't affect Asset IDs. It's not possible to have two assets with the same ID in the same project, regardless of the context setting.

Tip: If you need to keep assets unique by source text, you might consider disabling Asset IDs in your project settings.

Key expansion

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 flat ID "foo.bar".

The reverse happens when you export an ID containing a dot separator. This only applies to file formats that contain nested objects, and can be disabled by passing the no-expand option to the Export API.

Important: Watch out for overlapping identifiers when expanding flat keys to nested objects. "foo" and "foo.bar" cannot co-exist as scalar properties in most nested formats. See Key collisions for detailed examples of this common mistake.

Asset ID limitations

The rules for unique asset IDs are as follows:

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

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

Last updated by