Key referencing

Key referencing allows linking one key to another at translation level. Never again translate same strings twice.

Ilya Krukowski avatar
Written by Ilya Krukowski
Updated over a week ago

In many cases, your app may feature similar content across multiple strings. A common example is a "cancel" button appearing on various pages. Though these buttons might be represented by distinct translation keys, their textual values will be the same.

To prevent the need for repetitive translations of identical texts, we provide a feature called key referencing. This functionality allows you to create connections between two or more translation keys. When the translation for the "parent" key is updated, all associated "child" keys will automatically receive the same update, ensuring consistency and saving time.

How does it work?

First, let's clarify two essential concepts:

  • Referenced key β€” this is the "parent" key to which a link is established. Any updates to this key automatically trigger updates to all its "children".

  • Referring key β€” these are the "child" keys that link back to their "parent". They get automatically updated following any changes to their parent key.

On Lokalise, every translation key is given a unique ID upon creation. Links between keys are formed using these IDs.

For example, imagine a translation key with the ID 1234 designated as the parent (referenced key).

To link a child key to this parent, you would insert the following placeholder in the translation value for every referring key:

[%key_id:1234%]

This reference can be part of a sentence:

Hello, [%key_id:1234%]

And it's possible to use multiple references within the same string:

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

To facilitate this process, you can find these code snippets in the Clipboard dialog box for any key you wish to set as 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?