Labels and Translations

Labels and translations are essential to display the user interface in multiple languages.

Where label keys are neutral placeholders 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 is thus language independent, and a new language can be added without reconfiguring the system.

Label Keys

Label keys are generated automatically at runtime according to their location/function. They are requested everywhere a user requires textual input in the interface, e.g. on fields, actions, tooltips, or pop-ups.
Label keys are not stored separately in the file system, but are referred to in translation files. They show in the GUI, if not translated:

File's detail view without translations

File's detail view with English translations

How to translate label keys

Label Key Structure

Label keys are unique throughout the system and can be both global and module specific. They are generated by the system 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 in capitals, and their elements are 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 title
• L-GLOBAL-SEARCH_RESULT-ERROR for an error message

Label Key Types

To represent all possible usage options and places in the system, the following specifications are used 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 (more details).	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, required e.g. for pop-ups	L-M-TASK-SINGULAR L-M-TASK-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, Modules and 4Apps

When creating a custom field, the system automatically generates label keys that require translations for each language (see How to translate labels). If you develop a custom module or 4App, make sure to translate all three module name variants (L-M-{MODULE}, L-M-{MODULE}-SINGULAR, L-M-{MODULE}-PLURAL).

Info and Prompt Keys

The basic label key and its corresponding -INFO key (e.g., for a tooltip) are always generated by the system and will appear in the GUI. If you do not translate them, the technical key will display.

-PROMPT keys (for a placeholder, e.g. in a text field) are not generated automatically and will not appear in the GUI. If required, you need to add and translate the key in a .properties file.

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.

Label Fallback

If a module-specific translation cannot be found for a requested key, the system checks for an appropriate translation in the global locale folder.
This way, module-specific label keys do not have to be translated if they match the global translation.

Example: The translation fallback for L-FILE-FRIENDLYNAME is L-GLOBAL-FRIENDLYNAME.

For a global key, the system always checks whether a module-specific translation, too, has been stored and uses it instead.
This way, the global standard can be overwritten, and a specific translation can be assigned if required.

Example: The nonstandard translation of key L-FILE-DELETE is used instead of the standard L-GLOBAL-DELETE translation.

Exception

The fallback ignores:

• labels with a prefix (starting with e.g. L-M-, or L-V-)
• all custom labels

Permission prefixes L-P and L-PG will be fallbacked, though.

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.

.properties files are language specific and contain only one language. They are stored in corresponding language folders (locales) to assign them to a specific language. This way, the system can map the correct .properties files to a user's interface according to their stored user language.
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 Language Code (e.g. en_US or es_ES).

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 are not relevant for finding a label key's translation.

Encoding

Please note that .properties need to be saved with UTF-8 Encoding.

Reading Order

The basis for the translations displayed in the GUI is a hash map in the runtime. It is built with every reload from all .properties found in the installed apps (following the app order) and the custom folder. The names of the files are stored in alphabetical order.

1. properties from installed apps:

• global folders (e.g. global/locale/en_US/general.properties)
• module-specific folders (e.g. user/locale/en_US/general.properties)

2. properties from the custom folder:

• global folder
• module-specific folders

When Do Properties Overwrite Each Other?

Multiple apps: If a .properties file with the same file name + the same path is found in two apps, the .properties from the app loaded later according to the app order will overwrite the other .properties file.
Custom folder: If a .properties file with the same file name + the same path is found in one/multiple apps and the custom folder, the .properties from the custom folder will overwrite the other .properties file.

Example:

• CORE file global/locale/en_US/general.properties would be overwritten by

• DAM file global/locale/en_US/general.properties would be overwritten by

• custom file global/locale/en_US/general.properties

• DAM file global/locale/en_US/general_dam.properties will not overwrite

• CORE file global/locale/en_US/general.properties

3. At last, file translation_studio.properties, which holds custom translations made via the GUI, is loaded. Its content always overwrites the hash map content built up so far (GUI translation information).

Translation Order

After all .properties are considered and loaded into the runtime, their keys and translations are loaded (and overwritten) following the hash map's alphabetical order starting with "a".
Note that in the hashmap no distinction is made between a custom and a standard .properties file.

Example:

• L-M-FILE from custom file apple.properties is overwritten by
• L-M-FILE from standard file general.properties, which is overwritten by
• L-M-FILE from custom file zebra.properties

How to Safely Consider Custom Translations

If you want to customize a translation from a standard key, you can:

• use the GUI tools Translation Studio/Right-click menu to save your custom translation (recommended)
• store a .properties file in your custom folder that will be loaded alphabetically after the standard key's .properties file
• copy the whole standard .properties file with your additions into your custom folder

Translation Fallback

If no translation can be determined for a language, the system considers the fallback, or displays the label key. Missing translations are logged in admin snap-in Protocol overview/Missing translations.

Translation Studio File

All label changes made via the GUI are stored in only one file per language in your custom's global locale folders: translation_studio.properties.

At system start and reload, the label hash map is built of all .properties files from all apps' locale folders following the order described here.
If a translation_studio.properties exists in custom/global, its content is matched with the hash map. If differences occur, translation_studio.properties translations always override all other .properties files.
That way, GUI translations are displayed over the system's standard as well as other .properties files stored e.g. in a custom module folder.

Note that changes in the translation_studio.properties do not require a reload, they are displayed immediately.

Filesystem vs. GUI

Please note that as soon as a label key is translated in translation_studio.properties, you cannot overwrite it via the filesystem anymore. When loading, translation_studio.properties would overwrite your changes (compare reading order).

Duplicate Prevention

To prevent the translation_studio.properties files from growing with duplicate entries already stored in the apps, the custom .properties files, or the translation_studio.properties itself, a logic checks for duplicates as soon as a label translation is added or edited via the GUI.
The translation studio will only persist a delta to your custom folder. So if a provided translation matches the custom .properties, the entry in the translation_studio.properties is removed.

How to Translate Labels

When creating a custom metadata field, value option, feature permission, module, search group, etc., the system automatically generates the technical label keys for translation (creation syntax). In order to display a translation in the GUI, it must be accessible in a system's .properties file.

Please note: Label keys have to be translated for each available language separately in their respective locale folders (storage).

To add and translate label keys, or to edit the standard translation of a label (e.g. the explanation in a tooltip), you can:

• work in the filesystem and translate directly in your custom folder
• work in the GUI (no additional work in the file system required), and use either
  • the Right-click menu for a quick change in a pop-up window, or
  • admin snap-in Translation studio which additionally provides general label options

Deviant Storage and Loading Order

Please note that translation made in the GUI are stored in extra files translation_studio.properties which always overwrite translations made in the file system (technical functionality).

Translate Label Keys in the Filesystem

To edit or translate label keys in the file system, you work directly in the .properties files in your custom folder (global or module specific):

1. Open an appropriate (global/module-specific) .properties file.
2. If a folder or .properties file does not yet exist in your custom folder, create it (e.g. "my_custom_fields.properties").
3. Enter all keys you want to translate (e.g. copy & paste them from your GUI), followed by = and the translation. Make sure your key is written in capitals, and you do not include a space before or after the = (more on label key structure).
4. Save your files and clear your system's configuration cache.
5. If required, follow these steps for all available language folders.

Naming rules

The name of a .properties file is not relevant for the system. However, we suggest to sum up related keys or add them to an existing .properties file with related key translations (e.g., sum up all value options or permissions).

If default labels are changed for a customer system, individual properties files should be used.
Example: modules/user/locale/en_US/{customer name}.properties

Example 1: New Field

You create a new field "product_usp" in your file module and implement it in your metadata renderer. Its technical label and tooltip key are generated automatically:

• L-FILE-PRODUCT_USP
• L-FILE-PRODUCT_USP-INFO

As long as not translated, the corresponding label keys are displayed:

Display in the GUI without a translation

You can now copy these keys to an appropriate .properties file and translate them, and, optionally, also add key and translation for a -PROMPT placeholder.

L-FILE-PRODUCT_USP=Product USP
L-FILE-PRODUCT_USP-INFO=Please enter at least one USP
L-FILE-PRODUCT_USP-PROMPT=Unique unique unique

Your keys and translations in file custom_fields.properties in folder custom/file/locale/en_US

Result in the GUI

Example 2: Value Options

You implement new value option "for_magazine" with three values in your collection module's metadata renderer. The technical label keys are generated automatically:

• L-F_COLLECTION-V-FOR_MAGAZINE
• L-F_COLLECTION-V-FOR_MAGAZINE-INFO
• L-V-FOR_MAGAZINE-NATURE_PICTURES
• L-V-FOR_MAGAZINE-NATURE_PICTURES-INFO
• L-V-FOR_MAGAZINE-WORLD
• L-V-FOR_MAGAZINE-WORLD-INFO
• L-V-FOR_MAGAZINE-WOOD_AND_FOREST
• L-V-FOR_MAGAZINE-WOOD_AND_FOREST-INFO

As long as not translated, the corresponding label keys are displayed:

Display in the GUI without a translation

L-F_COLLECTION-V-FOR_MAGAZINE=Select a magazine
L-V-FOR_MAGAZINE-NATURE_PICTURES=Nature Pictures
L-V-FOR_MAGAZINE-NATURE_PICTURES-INFO=Select if collection is for Nature Pictures
L-V-FOR_MAGAZINE-WORLD=WORLD
L-V-FOR_MAGAZINE-WORLD-INFO=Select if collection is for WORLD
L-V-FOR_MAGAZINE-WOOD_AND_FOREST=Wood & Forest
L-V-FOR_MAGAZINE-WOOD_AND_FOREST-INFO=Select if collection is for Wood & Forest

Your keys and translations in file custom_value_options.properties in folder custom/global/locale/en_US

Result in the GUI

Right-click Menu

The quickest way to translate an untranslated label key or to edit a translation, is the right-click menu. A change made here directly changes file translation_studio.properties which overwrites all other translations.
Just right-click the appropriate label or label key and click "Translation properties" to open the translation pop-up:

Native right-click Menu

To access the browser's native right-click menu, just hold CTRL(STRG)/CMD while right-clicking.

Translation Studio

Admin snap-in General system configurations/System settings/Translation Studio lets you manage label translations and create new user languages. The labels and translations listed here resemble the content of all loaded .properties files (reading order and hash map).

In this snap-in you can:

• get an label key overview and filter
• add and edit translations
• export translations
• import translations
• create a new user language

Overview and Filter

All label keys from the system are listed here, with your selected language on the left, and a second language on the right. Both languages can be changed via the dropdown.
The list's sorting is based on the technical label key, by default in alphabetical order. You can also change the sorting by:

• label type (basic label, info, prompt)
• module

On the very left, you can filter the list, e.g. to search for a specific label key or translation, or to narrow down the list, e.g. to module specific label keys, label type or a specific context.

By activating "Custom GUI translation", you can search for all custom translations that were changed via the GUI (in this snap-in or via the right-click menu, i.e. that are stored in a translation_studio.properties).

Add and Edit Translations

Below each listed label key, its corresponding translation fields show the text displayed to the user. If a field is empty, no translation can be found in the file system. You have the option to add a translation to a still empty field, or to edit an existing translation.

Use the language dropdowns to compare languages and to match your translations. Use the back arrow in a translation field to get to the former entry (only as long as you do not save).

After you made your changes, save them via the toolbox. Your new translations display immediately after a page refresh.

Restore the Standard

Changes made in this snap-in overwrite the system's standard and former custom translations. Use filter "Translation Studio" to search for these files and use toolbox action "Reset translation" to restore the system's default translation.

Please note: Action "Reset translation" will reset and save immediately.

Export Translations

You can export your system's technical label keys with all available translations, e.g. to edit them outside the 4ALLPORTAL or to have new language translations added by an agency.

To export, just click toolbox action "Export translations", and the system automatically generates and downloads a file of format XLSX to your computer. Its structure looks like this (with two languages in the system):

key	en_US	de_DE
L-A-API	API	API
L-A-API_KEY	API Key settings	API-Key Einstellungen
L-A-API_KEY-MESSAGE	This is an overview of all assigned API keys.	Hier sehen Sie eine Übersicht mit allen vergebenen API-Keys.
L-A-API_KEY-TITLE	API Key settings	API-Key Einstellungen
L-A-APP_BACKUPS	Backups	Backups

Please note: This table contains all available languages with their translations. The sorting is "Label Key" (alphabetically).

Import Translations

You can also import translations to your 4ALLPORTAL by uploading an XLSX file following the same structure (label key to Language Code) as shown above. To import, just click toolbox action "Import translations" for an upload pop-up:

After dropping or selecting the XLSX file, click "Upload file". The imported translations are available after a page refresh.

XLSX Rules

• For a successful import, all languages in the XLSX must already be created with their Language Codes in your system.
• Adding a new row with a new key will create it in the system (e.g. a -PROMPT key).
• An XLSX file with the same filename can be imported multiple times.

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.

Create a New Language

If you require a new language in your system, you can create it via admin snap-in General system configurations/System settings/Translation Studio, toolbox action "New language":

In the create pop-up you can:

• enter a unique Language Code
  • Format: two letters in lowercase + underscore + two letters in capitals (region) (e.g. it_IT or en_GB)
• enter a corresponding language name (e.g. Italiano)
• activate your language if you want users to get to select this language in their profile
• enter the name of the new language for all other available languages in your system (e.g. Italian, Italienisch, L'italien)
• after saving, the system automatically creates a new language folder in custom/global/locale and adds file translation_studio.properties for GUI translations.
• log out and in again to see your new language

Manual Creation

You can as well create a new language directly in your file system. Add a language subfolder (e.g. it_IT) to each custom locale folder (global or module-specific) required and place at least one .properties files. The system automatically recognizes the new language after a reload.

Language Activation

You can activate and deactivate all created languages in admin snap-in General system configurations/System settings/General settings.

If activated, your new language can be selected by users in their profile. Make sure you only activate a language if all label keys are translated accordingly.