...

Introduction

The terms and phrases displayed by a client application based on the framework library our libraries such as our yuuvis® Momentum client as reference implementation can be localized for translated into custom languages according to the corresponding needs. For this purpose, each individual technical term used in the background can be mapped to a user-friendly localized term or phrase that will be displayed in the client application wherever instead of the technical term would be present. The built with our libraries allows for the localization of control elements (e.g., buttons or error messages). In order to provide a custom language in the selection list from which the users can select their preferred language, it has to be added to the client's main configuration. Furthermore, labels used in forms can be localized easily during runtime.

...

Localizing Control Elements

The localization of control elements is realized directly during the building build process of the client. JSON files are used as configuration files for the translations. The languages to be offered to users are specified in the client's main configuration.
>> Framework Library Installation and Configuration

...

Localizing Form Labels ...

The labels displayed in forms (e.g., object metadata forms) are localized by means of JSON configuration files as well. A distinction is made between tenant-specific labels available only within in one tenant and global labels available in all tenants. The tenant-specific localization files are managed by users with the role the access to the admin-controller endpoints of the Web-API Gateway (default: users with the YUUVIS_TENANT_ADMIN role). Their changes are applied only to their own tenant. Users with access to the system-controller endpoints (default: users with the role YUUVIS_SYSTEM_INTEGRATOR role) are allowed to manage the global localization files available in all tenants.

Whenever a new tenant is created and provided with its own tenant-specific resources like, e.g., a tenant schema, also a tenant-specific localization file also needs to be created. Otherwise the technical terms defined in the technical resource files will be displayed in the forms.

In order to retrieve or import localization files, the corresponding endpoints of the Web-API Gateway (API-WEB) can be used. Alternatively, the administrative graphical user interface of yuuvis® architect allows for a comfortable localization handling.

...

...

by means of Web-API Gateway

The endpoints for the management of localization files provided by the Web-API Gateway (API-WEB) are available only for users with specific administrative roles. Furthermore, the endpoints require the specification of the language for which the localization file should be retrieved/updated. The language has to be specified in ISO norm (e.g., de, en, es, fr, ...) in the request header for GET endpoints and in the request URL for the POST endpoints:

The endpoints can be called via Swagger-UI.
>> Web-API Gateway Endpoints

Alternatively, they can be called using cURL as shown in the following examples:

# For the system Management of a global localization file:

# GET e.g. theRetrieve the localization file for English language as a settingJSON via response:
curl -X GET "https://mydomain/api-web/api/admin/resources/text" -H "accept: application/json" -H "Accept-Language: en"
for
getting# aImport JSON-based response.

# POST e.g. a or update the localization file for Japanese language: 
setting via 
curl -X POST "https://mydomain/api-web/api/admin/resources/text/ja" -H "accept: */*" -H "Content-Type: application/json" -d "{all keys that are givegiven}"

# ForManagement of a tenant-specific tenantlocalization file for the tenant userof isthe logged -in for.user:

# Retrieve GET e.g. thethe localization file for English language setting via as a JSON response:
curl -X GET "https://mydomain/api-web/api/admin/resources/text" -H "accept: application/json" -H "Accept-Language: en"
for
getting# aImport JSON-based response.

#POST e.g. aor update the localization file for Japanese language: 
setting via 
curl -X POST "https://mydomain/api-web/api/admin/resources/text/ja" -H "accept: */*" -H "Content-Type: application/json" -d "{all keys that are givegiven}"

...

...

by means of yuuvis® architect

yuuvis® architect provides a support tool with a graphical user interface for client administrators. Based on the framework library, metadata forms of their client's graphical user interface can be modeled. Furthermore, users can be added or removed from the respective tenant and language settings can be customized.

The Localization tile is available on the dashboard for users with the YUUVIS_TENANT_ADMIN or YUUVIS_SYSTEM_INTEGRATOR roles.

...

These configurations are defined in different JSON files. There are two global localization configuration files that are available in all tenants: one for the localization of control elements provided by the framework library (e.g., buttons or error messages) and one for the localization of terms introduced via a global schema (e.g., labels for administrative fields in object forms). Additionally, each tenant has an own localization configuration file for terms introduced via its specific tenant schema (e.g., labels for metadata fields in object forms). This article describes how to define and apply all three localization configuration files to a client.

This article is written for administrators that will prepare an application based on the reference client for a new language. There are several parts that must be configured in a specific way.

Parts to be localized

If you want to localize an application you have to configure the following files and bring them into the correct place. The user interface showing by the client consists of these parts that have to be maintained differently:

• The clients are showing static labels coming from the client source project that includes the framework library. Both parts are handling files for each supported language containing keys and the labels showing up for the language the user has set up in the settings. The reference client is delivered with language files for English and German named en.json and de.json. Take the files of one language of the client project as well as of the framework library, create a new language file (e.g. ja.json e.g. for Japanese) and put all keys into that file. Translate the labels and place the new language file beside both existing ones as described below.
  • Configure the main.json configuration file and add the new language so the user can select it in the settings area of the client.
• The clients are showing dynamic labels (custom labels) as well. These are set up in the language files that support localizing technical names that are given in the configured schemas and forms. These language files are persisted in the config service using specific REST endpoints of the Web-API Gateway. There are two groups of language files. One group contains all globally used technical names that are part of the system schema as well as of the app schemas. After setting up a new environment the language files for resource en= English and de = German are persisted and containing all system-specific technical names like 'system:document' and 'system:folder'. The other group contains the technical names that are configured in a tenant schema if given.
  You need to fetch the one global language file (system) and if given a tenant-specific one, let them be translated for the wished new language and store them as described below.

Setting up the static labels

todos: describe where to find the language files in the client project: https://www.npmjs.com/package/@yuuvis/project

and where in the framework library: https://www.npmjs.com/package/@yuuvis/framework

Setting up the dynamic labels

todos:

For the system:

GET e.g. the English language setting via curl -X GET "https://mydomain/api-web/api/admin/resources/text" -H "accept: application/json" -H "Accept-Language: en" for getting a JSON-based response.

POST e.g. a Japanese language setting via curl -X POST "https://mydomain/api-web/api/admin/resources/text/ja" -H "accept: */*" -H "Content-Type: application/json" -d "{all keys that are give}"

For a specific tenant the user is logged in for.

GET e.g. the English language setting via curl -X GET "https://mydomain/api-web/api/admin/resources/text" -H "accept: application/json" -H "Accept-Language: en" for getting a JSON-based response.

POST e.g. a Japanese language setting via curl -X POST "https://mydomain/api-web/api/admin/resources/text/ja" -H "accept: */*" -H "Content-Type: application/json" -d "{all keys that are give}"

Notice: While creating a new tenant and setting up its specific tenant schema all the relevant dynamic language files containing the specific technical names have to be prepared as well.

Setting up a new environment with given schemas

In this case, you have finished configuring one environment (system plus relevant artifacts) and you want to set up a new environment including the translation files you have to bring the dynamic global language settings in place as described above.

...

>> Localization

Localizing Terms from Plug-ins

In case you need to extend translations with new keys, please specify translations in the plug-in configuration for each language in your system.
>> Extending Clients with Plug-ins

Language-specific Date, Time and Number Formats

Regardless of the availability of a localization file with language-specific terminology, a library-based client can support language-specific date, time and number formats according to the corresponding rules. The supported languages are listed below. Support for languages not listed below can be implemented by the yuuvis® Momentum development team upon request. As of 2022 Summer, it is not possible to implement the usage of special characters to replace AM and PM in a 12-hour system.

To configure display languages for the client, please refer to this article: Customizing the Main Configuration.

Summary

In client applications built with our libraries, all displayed terms and phrases can be localized for a custom language. While labels for control elements are defined already during the client configuration, the localization of labels in forms is possible at runtime via Web-API Gateway or yuuvis® architect.

Another Tutorial

...

...

Another Concept Article

...

Another interesting Tutorial

...