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.