# 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 (+ optional INFO/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 tab
  • L-GLOBAL-ADMIN-INFO_BANNER-BUTTON_CLOSE for a close button
  • L-GLOBAL-PAGE_X_OF_Y for a page counter
  • L-CE_ROLE-REFERENCE-POP-UP-TITLE for a pop-up's title
  • L-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.
  • L-GLOBAL-YES
  • L-GLOBAL-USERNAME
  • L-GLOBAL-SELECTION_COUNTER-MARKED
Extended labels -INFO
-PROMPT
{LABELKEY}-INFO
for tooltip (INFO) or prompt text (PROMPT). Always suffixed to a certain key.
  • L-GLOBAL-DELETE_ALL_OBJECTS-INFO
  • L-USER-FIRSTNAME-PROMPT
Module names -M-
L-M-{MODULE}
for a module's name
  • L-M-TASK
  • L-M-TASK-INFO
Module names -SINGULAR
-PLURAL
L-M-{MODULE}-SINGULAR
for the singular/plural form of a module, used e.g. in pop-ups
  • L-M-CONTACT-SINGULAR
  • L-M-CONTACT-PLURAL
Module fields -{FIELDNAME}
L-{MODULE}-{FIELDNAME}
for module-specific fields
  • L-CONTACT-FRIENDLYNAME
  • L-FILE-SIZE
Administration -AG-
L-AG-{ADMIN_SPACE}
for admin spaces in the mega menu
  • L-AG-MODULESETUP
  • L-AG-DEFAULT
Administration -ASG-
L-ASG-{SNAP-IN_GROUP}
for admin snap-in groups in the admin sidebar
  • L-ASG-APP_MANAGEMENT
  • L-ASG-API
Administration -A-
L-A-{SNAP-IN}
for a single admin snap-in
  • L-A-CLEAN_DATABASE
  • L-A-ROLE_CONFIG
Value Options -V-
L-V-{VALUEOPTION_NAME}-{VALUE}
for the single values of a unique value option (which itself does not require a label)
  • L-V-SALUTATION-MR
  • L-V-SALUTATION-MRS
Value Options -V-G-
L-V-{VALUEOPTION_NAME}-{VALUEGROUP_NAME}
for the group name of grouped value options
  • L-V-G-MIMETYPES-MIMETYPE_GROUP_DOCUMENTS
Permissions -P-
L-P-{PERMISSION} (global)
L-P-{MODULE}.{PERMISSION} (module-specific)
for feature permissions and presets (more details)
  • L-P-ALLOW_VERSION
  • L-P-FILE.SHOW_SAVE_BTN
Permissions -PG-
L-P-{MODULE}.{PERMISSION-GROUP}
for permission groups
  • L-PG-FILE-IMAGE EDITING
Conditional Operations -CO-
L-{MODULE}-CO-{FUNCTION}
for conditional operations, e.g. an action only appearing if a certain mimetype was selected
  • L-GLOBAL-CO-DEL-MULTIPLE
  • L-CE_ROLE-CO-CREATE
Metrics -ME-
L-ME-{METRIC_NAME}
L-ME-{METRIC_NAME}-{UNIT}
L-ME-{METRIC_NAME}-{UNIT}-SHORTCUT
for metrics, their unit and shortcut
  • L-ME-DATA
  • L-ME-DATA-BYTES
  • L-ME-DATA-BYTES-SHORTCUT
Dimensions -D-
L-D-{DIMENSION_NAME}
for dimensions
  • L-D-LOCALE
  • L-D-CHANNEL

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)
  • Module-specific
    • standard properties (e.g. user/locale/en_US/general.properties)
    • individual properties (e.g. user/locale/en_US/{customer_name}.properties)

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.

Request missing documentation