Keys are used to identify translatable text strings within software code. This allows the use of a key (as a code name for a translatable string) to be referenced only once by Phrase instead of for each required translation of the string.
A key can have multiple translations associated with it, each corresponding to a different language locale of the project. The function is similar to that of the primary key in relational databases with the translations being an attribute of the key. Keys are stored in resource files and are used to identify source and target languages.
The use of keys allows localization management platforms to present translatable text to translators without having to present code.
Keys do not normally need to be added to a project as they are ideally created when a resource file is uploaded through the tab of a project page.
To prevent keys from being picked up by the editor, use the blocking key functionality. To display keys in the editor but prevent them from being translated, use the exclude keys functionality.
Keys in a project can be duplicated by selecting More/Duplicate key in the section of a project page or at the top of the Strings editor pane.
Different translation keys with the same values across one or multiple projects can be linked to automate content updates. Linked keys are used to ensure consistency across projects and eliminate repetitive work on identical content.
Changes to keys can be reverted from the sidebar activity window in the Strings editor.
Note
When working with repositories (GitHub, GitLab, etc.) and deleting keys, the keys must be deleted from both Phrase and the repository to be permanently deleted. This is to prevent the accidental deletion of keys due to errors or accidents in either Phrase or the repository.
Keys names must be unique within one project.
There are a multiple strategies for naming keys:
-
Descriptive
The original text is identified by function. This may make it harder to identify the text when reading code, but will remain a constant.
Example:
-
Source strings (not recommended)
The original text itself is used as the key which making it easy to identify the use of the text. This is problematic as if the original text changes, it breaks the relationship with the translations.
Example:
If keys are not uploaded, they can be created manually.
To create a key, follow these steps:
-
From the tab, click Add key.
The Add key window opens.
-
From the tab, provide a , , any available and a .
-
Enable plural forms from the tab if required.
-
Select excluded languages from the tab if required.
-
Provide technical details in the tab if required.
For example, it is possible to set a character limit for translations in the field. If set, the character limit is displayed by an indicator in the Strings editor when editing the translations of the relevant key.
-
Click Save.
The key is added to the project and can be viewed on the tab.
Deleting a key from the editor or the tab will delete all associated translations of that key and cannot be reversed.
In projects with more than 10,000 keys, unmentioned keys will not be calculated in further uploads.
Blocking prevents whole keys from being added to a project; if the name of a blocked key appears in an uploaded file, that key is omitted and not added to the project.
Blocking is used to omit keys from a project so they are not managed at all.
Typically blocked keys:
-
Date and time format strings.
-
Keys including configurations.
-
Keys causing issues when managed with the Phrase gem.
Manage blocked keys in a separate language file that is not processed or maintained.
These keys can cause problems and if used should be blocked when a project is created.
-
activemodel.errors* -
number.format* -
number.currency* -
number.percentage* -
datetime.prompts*
To block a key, follow these steps:
-
From a project page, select the tab.
-
Click Add key to the blocked keys list.
The window opens.
-
Provide a name for the key or a regular expression (regexp) and click Save.
The key is added to the list.
Tip
AI chatbots can be very effective at generating and verifying regexp.
Use tools like Regex101 to test regexp with different inputs.
Keys can be later modified by clicking or deleted
.
Some keys may need to be excluded from certain languages and can be marked as being excluded. These keys are uploaded and exist within a project, but are ignored.
Excluded translations are:
-
Excluded from export of the related language.
-
Excluded from the related language reports.
If the content is empty it is not counted as untranslated.
-
Visible but not editable in the translation editor.
Exclusion options:
-
Exclude a single translation in a language within the translation editor.
-
Exclude multiple translations in a language within the translation editor.
-
Exclude multiple translations by selecting the languages when creating or editing the key.
To exclude a key, follow these steps:
-
From the keys page, click
for the key requiring exclusion.
The window opens.
-
Select the tab.
-
Select languages for exclusion.
-
Click Save.
The selection is excluded in the specified key.
Keys can also be excluded from within the editor by selecting the key and using the menu.