# Labels and Translations
Labels and translations are essential to display the user interface in multiple languages.
Where label keys are neutral placehoders that enable language-independent programming and configuration, language dependent translation files provide the actual text displayed directly to the user according to their selected language.
The system knows the stored language of a user and automatically uses the corresponding translation files to relate the right translation to a label key.
Each label key is unique in the system, but can be referred to by multiple translation files for multiple languages. The user interface does thus not have to be created in several language variants, and a new language can be added without reconfiguring the system.
# Label Keys
Label keys are the technical keys automatically generated by the system according to their usage. They are placed everywhere a user requires textual input in the interface, e.g. on fields, actions, tooltips, or pop-ups. Without translations, only keys are displayed:
File's detail view without key translations
File's detail view with English translations
# Label Key Structure
Label keys are unique throughout the system and can be both global and module specific. They are created according to a fixed scheme:
L
+GLOBAL
/{MODULE}
+ usage description/field name (+ optionalINFO
/PROMPT
)L-GLOBAL-CREATE
L-CONTACT-FIRSTNAME-INFO
Note that label keys are always in capitals, and their elements are always separated by a hyphen -
.
The usage description/field name part can contain a module's field, a button or tab, an action, a title, etc.:
L-CE_ROLE-MODULE-RIGHTS-TAB
for a tabL-GLOBAL-ADMIN-INFO_BANNER-BUTTON_CLOSE
for a close buttonL-GLOBAL-PAGE_X_OF_Y
for a page counterL-CE_ROLE-REFERENCE-POP-UP-TITLE
for a pop-up's titleL-GLOBAL-SEARCH_RESULT-ERROR
for an error message
# Label Key Types
To represent all possible usage options and places in the system, more specifications are required for key generation:
Type | Element/Syntax | Description | Examples |
---|---|---|---|
Global labels | -GLOBAL- L-GLOBAL-{FUNCTION} | for general terms/functions recurring in various places in the interface. |
|
Extended labels | -INFO -PROMPT {LABELKEY}-INFO | for tooltip (INFO ) or prompt text (PROMPT ). Always suffixed to a certain key. |
|
Module names | -M- L-M-{MODULE} | for a module's name |
|
Module names | -SINGULAR -PLURAL L-M-{MODULE}-SINGULAR | for the singular/plural form of a module, used e.g. in pop-ups |
|
Module fields | -{FIELDNAME} L-{MODULE}-{FIELDNAME} | for module-specific fields |
|
Administration | -AG- L-AG-{ADMIN_SPACE} | for admin spaces in the mega menu |
|
Administration | -ASG- L-ASG-{SNAP-IN_GROUP} | for admin snap-in groups in the admin sidebar |
|
Administration | -A- L-A-{SNAP-IN} | for a single admin snap-in |
|
Value Options | -V- L-V-{VALUEOPTION_NAME}-{VALUE} | for the single values of a unique value option (which itself does not require a label) |
|
Value Options | -V-G- L-V-{VALUEOPTION_NAME}-{VALUEGROUP_NAME} | for the group name of grouped value options |
|
Permissions | -P- L-P-{PERMISSION} (global)L-P-{MODULE}.{PERMISSION} (module-specific) | for feature permissions and presets (more details) |
|
Permissions | -PG- L-P-{MODULE}.{PERMISSION-GROUP} | for permission groups |
|
Conditional Operations | -CO- L-{MODULE}-CO-{FUNCTION} | for conditional operations, e.g. an action only appearing if a certain mimetype was selected |
|
Metrics | -ME- L-ME-{METRIC_NAME} L-ME-{METRIC_NAME}-{UNIT} L-ME-{METRIC_NAME}-{UNIT}-SHORTCUT | for metrics, their unit and shortcut |
|
Dimensions | -D- L-D-{DIMENSION_NAME} | for dimensions |
|
Custom Fields and Custom 4Apps
When creating a custom field, the system automatically creates a label key. If you develop a custom 4App, please consider the above structure and syntax rules when creating label keys for buttons, actions, etc.
# Permission Labels
Feature permissions and presets can be found and edited e.g. in the role configurations and the user profile. Related permissions can be grouped and do then require a group name.
Permission group and permission with yet untranslated label keys
Attention!
Unlike regular notation, permission label keys have a period (.
) between the module's name and the permission associated with that module.
# Translation Files
For the translation of neutral label keys translation files of format .properties
are used. They are simple text files listing the label keys followed by an equal sign =
and the translation:
L-GLOBAL-EXAMPLE=This is an example translation.
Translation files are language specific and contain only one language. So for each language, separate .properties
files must be stored in the file system.
The system determines a user's language and refers to the corresponding translation files. A user with stored English language gets the English key translations, a user with stored German language the German ones:
L-M-USER=User
L-M-USER-INFO=Go to User
L-USER-MAIN_GROUP_TITLE=User information
from the User module's general.properties
in folder en_US
L-M-USER=Benutzer
L-M-USER-INFO=Zu den Benutzern
L-USER-MAIN_GROUP_TITLE=Benutzerinformationen
from the User module's general.properties
in folder de_DE
# Storage and Folder Structure
Translation files are stored in locale
folders. Like label keys, translations, too, can be both global or module-specific:
- Global translation files are stored in the global
locale
folder. - Module-specific translation files are stored in each module's
locale
folder.
In a locale folder, a separate language subfolder for each available language is required. In order for the system to map the user's language to the right folder, their names must be equivalent to the unique script language code (en_US
, es_ES
, etc).
Inside the language subfolders, the actual .properties
files are stored. Their filenames are not language specific and can be the same in each language folder.
Note that for the system, only the subfolder's name is relevant. The file names and number of .properties
files do not matter for finding the label key's translation.
Encoding
Please note that .properties
need to be saved with UTF-8 Encoding.
# Reading Order
The .properties
are read-in one after the other. Later read content overwrites the values already read-in. The order is as follows:
1. All properties from the default folder (conf):
- Global
- default properties (e.g.
global/locale/en_US/general.properties
) - individual properties (e.g.
global/locale/en_US/{customer_name}.properties
)
- default properties (e.g.
- Module-specific
- standard properties (e.g.
user/locale/en_US/general.properties
) - individual properties (e.g.
user/locale/en_US/{customer_name}.properties
)
- standard properties (e.g.
2. All properties from the customer folder (custom):
- Global
- default properties
- individual properties
- Module-specific
- standard properties
- individual properties
- If content with the same label key exists in the HashMap, it will be overwritten hierarchically according to the described order.
- If no translation can be determined for a language, the system displays the label key. Missing translations are logged in admin snap-in
Protocol overview/Missing translations
.
# Variables in Translations
The translation of label keys may contain variables that are automatically replaced by the specified value: L-GLOBAL-TEST=My {$test_var} translation.
The following standard variables may be used in each translation:
Variable | Description |
---|---|
{$module} | Fills in the general name of the current module, e.g., "usage history". |
{$module_singular} | Fills in the name of a single object of the current module, e.g., "session". |
{$module_plural} | Fills in the name of several objects of the current module, e.g., "sessions". |
For the system to get a value, the labels of the three referred to variables must be translated for each module and language:
L-M-{module}
- L-M-F-COLLECTION=Collections
L-M-{module}-SINGULAR
- L-M-F-COLLECTION-SINGULAR=Collection
L-M-{module}-PLURAL
- L-M-F-COLLECTION-PLURAL=Collections
Example:
L-GLOBAL-DELETE_MULTIPLE_BEANS-MESSAGE=Do you really want to delete the selected {$module_plural}?
Variable {$module_plural}
would be replaced with "files" in the Files module, and "collections" in the Collections module.