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.