Multiple Language Support

Das BPC unterstützt die Verwendung mehrerer Sprachen. Die Bereitstellung der Sprachdaten erfolgt über separierte Sprachpakete. Der Übersetzungsservice kann über entsprechende APIs in kundenspezifische Module eingebettet werden.

Wahl der aktiven Sprache

Die aktuelle Sprache im Client wird beim Login festgelegt. Dabei werden an der Login-Maske alle aktuell verfügbaren Sprachen in einem Auswahldialog angeboten. Dabei wird die Vorbelegung anhand folgender Kriterien(absteigen nach Priorität) gesteuert:

  • Konfigurierte Sprache in BPC Core Services (ist noch offen)

  • Aktuelle Sprache des Browsers

  • Deutsch (falls Browser-Sprache nicht erfüllt werden kann)

Schnittstellenbeschreibung

Generell ist zu sagen, dass die Übersetzung von Text Key-Value basiert ist. Somit kann für einen "Key" je Sprache eine Übersetzung angeboten werden.

Abfragen der aktuellen Sprache

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

Bereitstellen von Modulspezifischen Texten

Jedes Frontend-Modul kann innerhalb seines (War-)Paketes je Sprache eine JSON-Datei enthalten, die jeweils zu einem "Key" den übersetzten Text enthält. Diese Dateien werden im Ordner resources/languages des Packages abgelegt. Der Dateiname setzt sich aus dem Sprachcode nach ISO 639-1 und der Endung ".json" zusammen (Beispiel de.json für Deutsch).

Die Sprachdateien können optional sowohl im Backend als auch im Frontend abgelegt werden. Es empfiehlt sich, die Textbausteine je nach ihrer primären Verwendung im Frontend oder Backend zu platzieren.

Die Keys müssen über alle Module hinweg eindeutig sein, um Überschneidungen mit bestehenden Keys zu verhindern. Es empfiehlt sich, die ID des eigenen Moduls als Prefix zu verwenden. Beispiel: MODULID_MEIN_KEY.

Dateiformat
{
    "KEY1": "Text 1",
    "KEY2": "Text 2",
    "KEYn": "Text n"
}
Demo Modul Beispielstruktur
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-Modul

Die Sprachdateien für Backend-Module sollten im Ordner resources/languages innerhalb des Backend-Pakets abgelegt werden. Der Aufbau der JSON-Dateien ist identisch zu dem der Frontend-Module.

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

Konsumieren von Texten

Um in der GUI übersetzte Text zu erhalten und zu verwenden, werden zwei Möglichkeiten angeboten.

API Funktion getTranslation

KEY → Value

Die Funktion getTranslation hat im Wesentlichen drei verschiedene Funktionsmodi. Im einfachsten Fall wird einfach ein KEY übergeben und man erhält die Übersetzung. Wird keine Übersetzung gefunden, so erhält man den KEY zurück.

Beispiel:

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

KEY → Value → Template

Als Übersetzungstext kann auch ein Template angegeben werden. Dieses muss die Ext.XTemplate Syntax erfüllen. In diesem Fall wird der Funktion ein Objekt der folgenden Art übergeben:

{
	key: "LANGUAGE_KEY",
	data: DATA_OBJECT
}

Dabei wird der Übersetzungstext anhand des "key"-Arguments aufgelöst und das Ergebnis in ein XTemplate überführt. Anschließend wird das Template mit dem data-Argument aufgerufen.

Beispiel:

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

Es ist auch möglich ein Template und mehrere Language-Keys zu übergeben. Dann werden die Keys aufgelöst und können im Template verwendet werden. Das Parameter-Objekt muss wie folgt aussehen:

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

Beispiel

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

Objekt mit Inhalten

AB V3.2.0

Die API Methode kann auch ein Objekt mit Inhalten zu mehreren Sprachen entgegennehmen und liefert dann den Inhalt passend zu der aktuellen Sprache zurück.

Beispielobjekt:

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

Bei diesem Beispiel wird je nach Sprache "grün" (deutsch), "green" (englisch) oder undefined (andere Sprache) zurückgegeben.

Singleton Klasse

Über das Singleton "BpcCommon.lang.Current" stehen alle vorhandenen Übersetzungen der aktuellen Sprache zur Verfügung. Wobei jeder "KEY" als Attribut am Singleton vorliegt. In dem Fall, dass für ein Key keine Übersetzung der aktuellen Sprache vorliegt, ist der Wert gleich dem Key.

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

Impliziter Aufruf über Bind-String

Beim "Binden" innerhalb von ExtJS kann die "getTranslation"-Funktion auch implizit aufgerufen werden. Dabei kann der "KEY" fest vorgegeben werden oder aus dem Ergebnis einens gebundenen Wertes stammen.

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

Verwendung von "localized" an ExtJS Komponenten

Für ExtJS-Komponenten kann man über ein spezielles Attribut andere Attribute der Komponente (Ext.Component) übersetzen lassen. Diese wird bei der Instanzerzeugung ausgewertet, sodass eine Deklaration möglich ist, bevor das BPC die Sprachdaten geladen hat. Da intern auch die Funktion BpcCommon.Api.getTranslation verwendet wird, können auch alle drei Funktionsvarianten genutzt werden.

Beispiel:

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

    localized: {
		text: "BPC_ERROR",
		tooltip: "BPC_BUTTON_TOOLTIP"
	}
});
Variante2
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"
	}
});
Variante 3
Ext.define('moduleid.Button', {
    extend: 'Ext.button.Button',

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

Formatierungen

Die Formatierung von Zahlen und Datumsangaben in Standard ExtJS-Komponenten wird über das Einbinden der passenden "ExtJS locale" über das BPC gewährleistet (siehe auch Localization in Ext JS).


Keywords: