Lokalisierung¶

Unter Lokalisierung versteht man die Zuordnung von regionalen Merkmalen wie Sprache, Bilder, Währungen zu einer Webseite.

Lokalisierung¶

Bei der Anzeige einer lokalisierten Webseite gibt es einige Herausforderungen zu meistern. Welche Sprache soll angezeigt werden, welche Währung und wie erkenne ich die gewünschte Sprache? Die Bestimmung der Sprache erfolgt am besten auf Serverseite, da hier - über den Request und die Kontodaten - alle Daten zur Verfügung stehen und genügend Ressourcen für die Auswertung gegeben sind.

Hinweis

Das Frontend sollte nicht mit eine umfangreichen Lokalisierung aufgebläht werden.

Dokumentensprache auslesen¶

Die wichtigste Funktion ist in diesem Zusammenhang die Funktion:

Alvine.i18n.getLocaleOfDocument(urlLocalePosition, defaultLanguage);

Mit Hilfe dieser Funktion kann die Locale des Dokuments ermittelt werden, die der Server festgelegt hat. Will man zusätzlich eine andere Defaultsprache als englisch festlegen, so muss man noch den gewünschten Parameter übergeben.

Alvine.i18n.getLocaleOfDocument('de');

Ist im Dokument selber kein Locale definiert, dafür aber in der URI, so kann man die Option scannen der URI aktivieren. Dazu muss die Position der Locale in der URI übergeben werden. Ist die URL zum Beispiel http://www.example.com/part/de/page so kann man mit dem ersten Parameter das de aus der URL übernehmen:

Alvine.i18n.getLocaleOfDocument(1);

Im folgenden Beispiel werden beide Parameter übergeben

Alvine.i18n.getLocaleOfDocument(1, 'de');

Das Ergebnis dieser Methode ist ein Objekt vom Typ Locale, zum Beispiel:

Locale {
   language: "en", 
   region: "CN", 
   script: "Hans", 
   variants: "rozaj", 
   extensions: undefined
   }

Dokumentenlokale setzen¶

Nach dem ersten Abfragen der Sprache wird der Wert zwischengespeichert und nicht erneut aus dem Dokument ermittelt. Möchte man die Sprache des Dokuments ändern, so muss man die Funktion

Alvine.i18n.setDocumentLocale(locale);

aufrufen. Diese Funktion schreibt den Wert der Locale in den HTML-Tag und setzt die interne Variable auf den neuen Wert. Der Parameter locale kann entweder eine Zeichenkette oder ein Objekt vom Typ Locale sein.

Lokale aus Zeichenkette erstellen¶

Um ein Lokale-Objekt zu erstellen, kann auf die Funktion Alvine.i18n.getLocale() zurückgegriffen werden. Diese Funktion zerlegt eine Sprach-Zeichenkette und gibt ein Locale-Objekt mit den entsprechenden Eigenschaften zurück.

Alvine.i18n.getLocale('en_Hans_CN_nedis_rozaj_x_prv1_prv2');

Locale {
   language: "en", 
   region: "CN", 
   script: "Hans", 
   variants: "rozaj", 
   extensions: undefined
   }

Diese Methode hat einige Einschränkungen der Erkennung mehrerer Varianten und privaten Erweiterungen, die aber nicht für den normalen Betrieb einer Website ins Gewicht fallen dürfte.

Alvine.i18n.getLocale('zh-cmn-Hans-CN');

Locale {
   language: "zh", 
   region: "CN", 
   script: "Hans", 
   variants: undefined, 
   extensions: "cmn"
   }

Alvine.i18n.getLocale('de-AT');

Locale {
   language: "de", 
   region: "AT", 
   script: undefined, 
   variants: undefined, 
   extensions: undefined
   }

Umwandlung in Zeichenkette¶

Bei der Umwandlung der Locale in eine Zeichenkette wird die Locale::toString() aufgerufen. Diese Funktion besitzt als Parameter einen Filter. Mit Hilfe dieses Filters lassen sich beliebige Variationen der Eigenschaften erstellen.

locale = Alvine.i18n.getLocale('zh-cmn-Hans-CN');

// Ausgabe der Locale als Zeichenkette
console.log(locale.toString());
// -> zh-cmn-Hans-CN

// Nur die Region
console.log(locale.toString(['region']));
// -> CN

// Die Region gefolgt von der Sprache
console.log(locale.toString(['region','language']));
// -> CN-zh

Ressourcendatei laden¶

Lokalisierte Zeichenketten können aus einer Ressourcendatei nachgeladen werden. Wird in einem Dokument mit der Lokalen zh-cmn-Hans-CN die Methode Alvine.i18n.loadLocaleResource() aufgerufen,

Alvine.i18n.loadLocaleResource()

so versucht die Funktion der Reihe nach folgende Dateien zu laden:

/resource/locale/zh-cmn-Hans-CN.json
/resource/locale/zh-cmn-Hans.json
/resource/locale/zh-cmn.json
/resource/locale/zh.json

Um Resourcen-Dateien von einer anderen URL zu laden, muss der Funktion der Parameter url übergeben werden.

Alvine.i18n.loadLocaleResource('mylocale')

Jetzt werden die Dateien im Verzeichnis mylocale/ gesucht:

/mylocale/zh-cmn-Hans-CN.json
/mylocale/zh-cmn-Hans.json
/mylocale/zh-cmn.json
/mylocale/zh.json

Wird eine Datei gefunden und vom Server mit Status 200 zurückgeliefert, so werden weitere Versuche abgebrochen. Um an die geladene Sprachdatei zu kommen, muss das Event loadresource.DONE abonniert werden.

jQuery(window).on('loadresource.DONE', function(event, resource) {
   // code
})

Fehler beim Laden einer Datei können über das Event loadresource.FAIL abonniert werden.

jQuery(window).on('loadresource.FAIL', function(event, resource) {
   // code
})

Das Ergebnis ist eine Objekt vom Typ Resouren. Mit der Methode Resource::get() können die einzelnen Texte geholt werden. Resource ist von Map abgeleitet (siehe Map)

resource.get('key')
// -> mein text

Objektreferenz¶

Locale¶

Locale(language, region, script, variants, extlang, privateValue)

Beschreibung

Hinweis

Die Funktion ist ein Konstruktor und muss mit new aufgerufen werden.

Parameter-Liste

language (String)

Sprache (zum Beispiel de). In diesem Parameter darf nicht die Region oder andere Werte mitgegeben werden. Der Wert 'de-DE' würde nicht zu dem gewünschten Ergebnis führen, sondern den Wert de-DE in die Sprache schreiben!

region (String)

Region (zum Beispiel DE)

script (String)

Script

variants (String)

Variante

extlang (String)

Erweiterungen

privateValue (String)

Private Werte

Rückgabewert

Neues Locale-Objekt

Locale.toString(filter)

Beschreibung

Gibt die Lokale als Zeichenkette zurück

Parameter-Liste

filter (Array)

Wird der optionale Filter angegeben, so werden nur im Filter angegebene Bestandteile in der Zeichenkette verwendet. new Alvine.i18n.getLocale('de-DE').toString(['language']) gibt nur de zurück. Gültige Werte sind: language, extlang, script, region, variants und privateValue

Rückgabewert

Zeichenkette mit den Werten der Lokalen. Die einzelnen Werte sind mit einem Bindestrich getrennt. Beispiel: de-DE

Resource¶

Resource()

Beschreibung

Eine Resourcen-Map von Alvine.Types.Map abgeleitet hält die Zeichenketten für eine bestimmte Sprache.

Hinweis

Die Funktion ist ein Konstruktor und muss mit new aufgerufen werden.

Rückgabewert

Neues Resourcen-Objekt

Resource.addTag(tag)

Beschreibung

Fügt einen Tag zum Objekt hinzu

Parameter-Liste

tag (String | Array)

Der Tag wird dem Objekt zugeordnet. Wird ein Array übergeben, zerlegt diese Methode dieses in einzelne Tags.

Rückgabewert

Referenz auf Objekt

Resource.removeTag(tag)

Beschreibung

Entfernt einen Tag vom Objekt

Parameter-Liste

tag (String | Array)

Der Tag wird vom Objekt entfernt. Wird ein Array übergeben, zerlegt diese Methode dieses in einzelne Tags.

Rückgabewert

Referenz auf Objekt

Resource.getTags()

Beschreibung

Gibt ein Objekt vom Typ Alvine.Types.Collection mit allen Tags zurück.

Rückgabewert

Alvine.Types.Collection mit allen Tags. Änderungen an dieser Collection führen nicht zur Änderung am Objekt.

Funktionsreferenz¶

getLocaleOfDocument(urlLocalePosition, defaultLanguage)

Beschreibung

Diese Methode sucht die Sprache, in der das Dokument verfasst wurde. Als erstes wird versucht die Sprache anhand des Lang-Attributes im HTML-Tag zu ermitteln. Als zweiter Weg kann die URL herangezogen werden. Hierzu muss für den Parameter urlLocalePosition ein Wert angegeben werden.

Parameter-Liste

urlLocalePosition (String | Integer)

Position des Locale-Zeichenkette in der aufrufenden URL. Lautet die URL zum Beispiel /start/de/home, so steht die Locale an 2 Stelle.

Parameter-Liste

defaultLanguage (String)

Standardsprache, wenn keine Sprache im HTML-Tag noch in der URL gefunden wird.

Rückgabewert

Alvine.i18n.Locale des Dokuments

setDocumentLocale(locale)

Beschreibung

Diese Funktion setzt das HTML-Lang-Attribute auf den Wert der übergebenen Lokale.

Parameter-Liste

locale (Alvine.i18n.Locale | String)

Wert der Sprache des Dokuments

Rückgabewert

Kein Rückgabewert

getDefaultLocale()

Beschreibung

Gibt die Default-Lokale englisch zurück.

Rückgabewert

Alvine.i18n.Locale('en')

getDefaultLanguage()

Beschreibung

Gibt die Default-Sprache englisch zurück.

Rückgabewert

en

getDefaultURL()

Beschreibung

Gibt die Default-URL /resource/locale/ zurück.

Rückgabewert

/resource/locale/

getLocale(locale)

Beschreibung

Diese Methode erstellt aus einer Zeichenkette nach RFC4646 ein Objekt vom Typ Alvine.i18n.Locale

Parameter-Liste

locale (String)

Zeichenkette mit der gewünschten Locale, zum Beispiel de-DE

Rückgabewert

Alvine.i18n.Locale