In many cases, your app might have similar content across multiple strings. A common example is a "cancel" button that appears on different pages. Even though these buttons might be tied to different translation keys, their text is the same.

To avoid the hassle of translating identical texts repeatedly, we offer a feature called key referencing. This functionality lets you link two or more translation keys together. When the translation for the "parent" key is updated, all linked "child" keys automatically receive the same update. This ensures consistency and saves you time.

Let's clarify two essential concepts:

In Lokalise, every translation key is assigned a unique ID when it’s created. Links (references) between keys are formed using these IDs.

For example, let’s say a translation key with the ID 1234 is 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 each referring key:

This reference can also be part of a sentence:

You can even use multiple references within the same string:

To make this process easier, you can find these code snippets in the Clipboard dialog box for any key you want to set as a parent.

You’ll be presented with a dialog box that looks like this:

Copy the value under the Reference by Lokalise key ID section.

Additionally, you can add references using key names in the following format:

In this case, you're using the key name instead of the key ID. However, it’s often better to use key IDs because they can’t be modified, unlike key names.

Let’s say your app has a dialog with the following content:

In this dialog, you have two repeated strings: "Cancel" and "Proceed." Let's create the corresponding translation keys on Lokalise:

Once the keys are created, we'll establish links. To make "Cancel" and "Proceed" the reference (parent) keys, you’ll need to copy their IDs from the Clipboard dialog.

Next, let’s modify the English translation for the cancel_or_proceed key:

In this step, replace the "Cancel" and "Proceed" words with links to their corresponding keys, then save the translation value.

When you see the green highlighting, it means the reference was successfully created. Now, whenever the English translation for "Cancel" or "Proceed" is updated, the cancel_or_proceed key will be automatically modified. For other languages, you can use the cross-referencing feature.

If you ever need to break the link, simply edit the cancel_or_proceed translation and remove the key_id placeholders.

Let’s say you have two translation keys: cancel and cancel2, and you've already established a link for the base language like this:

You’ll likely want to create similar links for other languages. While you could do this manually, it’s a tedious process. Instead, you can use a special bulk action to automate this task. Start by ticking the checkbox next to the cancel2 key and selecting Cross-reference all languages... from the bulk actions menu.

Next, click Proceed. This operation will automatically check all non-base languages related to these keys. If the content is empty and the base language translation is linked to a key, the same link will be applied to all other languages.

However, keep in mind that this feature won’t work if your base language value contains multiple key references, as explained in the Key referencing example section.

You can choose whether to display key references as text or as key identifiers by toggling the following button in the project editor:

When this option is enabled, references will be displayed as text with green highlighting. If disabled, references will be shown as key identifiers.

Manually creating references for duplicate keys can be tedious. To simplify this, you can use the Duplicate finder, which automates the process. For more details and usage examples, check out the Dealing with duplicates article.

By default, when you download translations from Lokalise, all reference placeholders will be automatically replaced with the corresponding translation values.

If you prefer to keep the references as placeholders, expand the Advanced settings dropdown on the Download page and tick the Disable referencing option:

In this case, all references will be exported as they are:

You can reference a key from another project within your team. To do this, go to the project of your choice, copy the key ID, and use it when setting up references as explained earlier.

To properly preview or export translations, make sure you have access to the project where the referenced key originates.