Key referencing
Key referencing allows linking one key to another at translation level. Never again translate same strings twice.
Nick Ustinov avatar
Written by Nick Ustinov
Updated over a week ago

There are many cases where you have similar content in multiple strings. A good example is a "cancel" button that might be displayed on multiple pages of your app. These buttons will probably be represented as different translation keys but their values will be identical.

To help you avoid translating the same texts over and over again, we offer key referencing. Using this feature, you can establish a link between two or more translation keys. Whenever the translation value for the "parent" key is modified, all "children" keys will be updated automatically.

Index

How does it work?

First of all, let's introduce two important terms:

  • Referenced key β€” the parent key that we establish a link to. Whenever this key is updated, all its children should be updated automatically.

  • Referring key β€” this is the child key that links to its parent. It is automatically updated whenever its parent changes.

Each translation key on Lokalise has a unique ID that is automatically assigned when a key is created. References are created using these IDs.

Suppose, we have a translation key with an ID 1234 that should act as a parent (referenced key).

To establish a link, we have to provide the following placeholder as a translation value for every referring key:

[%key_id:1234%]


Reference can be used as a part of a sentence:

Hello, [%key_id:1234%]


Multiple references can be used as well:

[%key_id:12%], [%key_id:34%]!


You can get these snippets in the Clipboard for the key you want to make a parent:

You'll be presented with the following dialog:

Please note that you can also add references using key names in the following format:

[%key:welcome%]

In this case you are saying key, not key_id, and provide the name itself. Still, it might be beneficial to use key IDs because they cannot be modified in contrast to key names.

Key referencing example

Suppose your app has the following dialog:

As you can see, we have two duplicating strings: Cancel and Proceed. Let's create the corresponding translation keys on Lokalise:

Next, let's establish links. I would like cancel and proceed to become references (parent) keys therefore I'll copy their IDs from the Clipboard dialog.

Now let's modify English translation for the cancel_or_proceed key:

As you can see, we're replacing the "Cancel" and "Proceed" words with the links to the corresponding keys. Save the translation value:

This green highlighting means that the reference has been successfully created. Whenever cancel or proceed English translation is changed, the cancel_or_proceed will be modified automatically. To create references for other languages, you can take advantage of the cross-referencing feature as explained in the corresponding section.

You can break the link by modifying the cancel_or_proceed translation and removing the key_id placeholders.

Referencing all languages

Let's suppose we have two translation keys: cancel and cancel2 and we've already established a link for the base language in the following way:

You will probably want to create similar links for other languages. Of course, you can do it manually but it's quite tedious. Instead, you can take advantage of a special bulk action to perform this operation automatically. Tick the checkbox next to the cancel2 key and choose Cross-reference all languages... from the bulk actions menu:

Then click Proceed. This operation will look up all the non-base languages related to these keys and in the case that the content is empty and the base language translation is linked to a key, it will do the same for all other languages.

Please note that this feature will not work if your base language value contains multiple key references as shown in the previous section.

Displaying key references as text

You can enable or disable showing key references as text by clicking on the following button:

If this option is enabled, your references will be shown as texts with green highlighting.

If this option is disabled, your references will be shown as key identifiers.

Linking duplicates

Manually creating references for duplicate keys is quite tedious therefore you can take advantage of the Duplicate finder that does heavy lifting for you. Please find more information and the usage examples in the corresponding article.

Referencing and downloading translation files

By default, when downloading translations from Lokalise back to your PC, all reference placeholders will be automatically replaced with the corresponding translation values.

If you don't want this to happen, then expand the Advanced settings dropdown on the Download page and tick the Disable referencing option:

In this case all references will be exported as is:

Cross-project referencing

You can reference a key from other projects within your team. To achieve that, simply proceed to another project of your choice, copy any key id, and use it when establishing references as explained above.

In order to properly preview or export translations, you should have access to the project where the referenced key originates from.

Known limitations

  • it is not possible to reference plural keys. If you try to reference a plural key it'll paste JSON string plural instead of the actual values.

Did this answer your question?