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. 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.
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.
Changes to keys can be reverted from the sidebar activity window in the editor.
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.
-
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.
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 that 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*
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.