Multiple Language Support

The BPC supports the use of multiple languages. Language data is provided via separate language packages. The translation service can be embedded into customer-specific modules using the appropriate APIs.

Selecting the Active Language

The current language in the client is set during login. All currently available languages are displayed in a selection dialog on the login screen. The default selection is determined based on the following criteria (in descending order of priority):

Configured language in BPC Core Services (still pending)
Current browser language
German (if the browser language cannot be met)

Interface Description

In general, the translation of text is key-value based. This means that a translation can be provided for each language for a given "key."

Querying the Current Language

BpcCommon.Api.getSetting("_core","language")

Providing Module-Specific Texts

Each frontend module can include a JSON file for each language within its (War) package, with each file containing the translated text for a specific "Key." These files are stored in the package’s resources/languages folder. The filename consists of the language code according to ISO 639-1 and the ".json" extension (example: de.json for German).

The language files can optionally be stored in both the backend and the frontend. It is recommended to place text snippets in either the frontend or backend depending on their primary use.

Keys must be unique across all modules to prevent conflicts with existing keys. It is recommended to use your module’s ID as a prefix. Example: MODULID_MEIN_KEY.

File format

{
    "KEY1": "Text 1",
    "KEY2": "Text 2",
    "KEYn": "Text n"
}

Demo module example structure

packages/local/demo/
├── resources/
│   ├── languages/
│   │   ├── de.json
│   │   └── en.json
└── src/
    ├── main.js
    └── ...

packages/local/MODULID/resources/languages/de.json

{
    "MODULID_GREETING": "Guten Tag",
    "MODULID_FAREWELL": "Auf Wiedersehen",
    "MODULID_THANKS": "Vielen Dank"
}

packages/local/MODULID/resources/languages/en.json

{
    "MODULID_GREETING": "Hello",
    "MODULID_FAREWELL": "Goodbye",
    "MODULID_THANKS": "Thank you"
}

Backend module

The language files for backend modules should be stored in the resources/languages folder within the backend package. The structure of the JSON files is identical to that of the frontend modules.

Example Structure (Backend)

backend-module/src/main/
├── resources/
│   ├── languages/
│   │   ├── de.json
│   │   └── en.json
└── ...

Consuming Texts

There are two ways to retrieve and use translated text in the GUI.

API Function getTranslation

KEY → Value

The getTranslation function essentially has three different modes of operation. In the simplest case, you simply pass a KEY and receive the translation. If no translation is found, the KEY is returned.

Example:

//current language is en
> BpcCommon.Api.getTranslation("CORE_ERROR")
"Fehler"
> BpcCommon.Api.getTranslation("NOT_EXISTING_KEY")
"NOT_EXISTING_KEY"

KEY → Value → Template

A template can also be specified as the translation text. This must comply with the Ext.XTemplate syntax. In this case, an object of the following type is passed to the function:

{
	key: "LANGUAGE_KEY",
	data: DATA_OBJECT
}

The translation text is resolved based on the "key" argument, and the result is converted into an XTemplate. The template is then called using the data argument.

Example:

Language File

{
	"GREETING": "Guten Tag Herr {lastName}. Darf ich {firstName} sagen?"
}

> BpcCommon.Api.getTranslation({
	key:"GREETING",
	data: {
		firstName: "Hans",
		lastName: "Mustermann"
	}
);
"Guten Tag Herr Mustermann. Darf ich Hans sagen?"

TEMPLATE → KEYS

It is also possible to pass a template and multiple language keys. The keys are then resolved and can be used in the template. The parameter object must look like this:

{
	tpl: "XTEMPLATE_STRING",
	keys: [LANGUAGE_KEY1,LANGUAGE_KEY2,LANGUAGE_KEYn]
}

Example

Language File

{
	"GREEN": "grün",
	"RED": "rot"
}

Object with content

AS OF V3.2.0

The API method can also accept an object containing content for multiple languages and then returns the content corresponding to the current language.

Example object:

Language File

{
	"de": "grün",
	"en": "green"
}

In this example, "grün" (German), "green" (English), or undefined (other language) is returned depending on the language.

Singleton Class

All available translations for the current language are accessible via the singleton "BpcCommon.lang.Current". Each "KEY" is available as an attribute of the singleton. If no translation for a key exists in the current language, the value is equal to the key.

//current language is en
BpcCommon.lang.Current.MONITOR_DELETE_FILTER_TOOLTIP

Implicit call via bind string

When “binding” within ExtJS, the “getTranslation” function can also be called implicitly. In this case, the “KEY” can be hard-coded or derived from the result of a bound value.

Variant 1

(...)
viewModel: {
   data: {
      vmVariable: "LANGUAGE_KEY"
   }
}
(...)
bind: "Statischer Text und eine Übersetzung {vmVariable:translate}",
(...)

Variant 2

(...)
bind: "Statischer Text und eine Übersetzung {translate:translate('LANGUAGE_KEY')",
(...)

Using "localized" on ExtJS Components

For ExtJS components, you can use a special attribute to have other attributes of the component (Ext.Component) translated. This is evaluated during instance creation, allowing for a declaration before the BPC has loaded the language data. Since the function BpcCommon.Api.getTranslation is also used internally, all three function variants can be utilized.

Example:

Variant 1

Ext.define('moduleid.Button', {
    extend: 'Ext.button.Button',

    localized: {
		text: "BPC_ERROR",
		tooltip: "BPC_BUTTON_TOOLTIP"
	}
});

Variant 2

Ext.define('moduleid.Button', {
    extend: 'Ext.button.Button',

    localized: {
		text: {
			key: "BPC_LANGUAGE_KEY_WITH_TEMPLATE_STRING",
			data: {
				eins: 1,
				zwei: 2
			}
		},
		tooltip: "BPC_BUTTON_TOOLTIP"
	}
});

Variant 3

Ext.define('moduleid.Button', {
    extend: 'Ext.button.Button',

    localized: {
		text: "BPC_ERROR",
		tooltip: {
			tpl: "<h1>{BPC_ERROR}</h1>",
			keys: ["BPC_ERROR"]
		}
	}
});

Formatting

The formatting of numbers and dates in standard ExtJS components is ensured by including the appropriate "ExtJS locale" via BPC (see also Localization in Ext JS).

Keywords: