Main menu

What is a Lookup Key?

Lookup keys are what your software uses to find translations in a file

Different platforms look up translations in different ways. For example Gettext uses the full source text to index translations, whereas many platforms prefer a language-agnostic key that doesn't change even when the source text changes.

There are advantages and disadvantages to both methods, but most likely you've decided which you prefer and just need to ensure that Loco is doing things the way you expect.

Platform defaults

There are two situations in which you may need to specify a lookup key:

  1. When importing files, you can specify the key mapping.
  2. When exporting files you can specify an alternative index.

Loco will automatically use the most common default for the file format you're working with, but this can be altered if you're doing something non-standard. The import and export APIs support the following values of the index parameter to change this behaviour:

"id"

Indexing by "id" will override the default lookup key and use your asset ID to uniquely identify strings.

This is the default for most file formats, but most commonly is NOT the case for Gettext files. If you need to look up your translations with something like translate("page-title") instead of translate("Welcome") then this is the option you need.

When using the API you can append your export query with ?index=id

"text"

Indexing by "text" will override the default lookup key and use your full source text to uniquely identify strings.

This is the default for only a few file formats including Gettext PO, POT and MO files. With this option you might look up your translations with something like translate("Welcome") instead of translate("page-title"). So if you needed to force a JSON file to use full text keys, you would have to tell Loco to use this option.

When using the API you can append your export query with ?index=text

Aliases

In addition to the built-in "id" and "text" keys, you can export files indexed by any asset alias you've defined in your project.

 See also