Entwicklungs-HOWTO

Um in den Genuss der vorhandenen Gettext-Übersetzungen auch in JavaScript-Code zu kommen, verwenden wir in Stud.IP einen speziellen Web-Service, der ausgesuchte Übersetzungen in JavaScript-Code umwandelt und diese für die von Eli Grey geschriebene l10n.js-Bibliothek verfügbar macht.

Web-Service

Der Web-Service findet sich in jeder Stud.IP-Installation ab Version 2.0 unter der URL: dispatch.php/localizations/{locale}

Auf dem offiziellen Entwicklungsserver der Stud.IP Core Group können daher die deutschen Übersetzungen unter:

http://develop.studip.de/studip/dispatch.php/localizations/de_DE

und die englischen unter:

http://develop.studip.de/studip/dispatch.php/localizations/en_GB

erreicht werden.

Sollte man ein nicht verfügbares Länderkürzel angeben, liefert der Web-Service den Status-Code 406 (Not acceptable) und eine JSON-Liste mit den tatsächlich verfügbaren locales.

Dieser Web-Service wird von den folgenden Dateien (und damit auf nahezu jeder Seite) automatisch eingebunden, wobei das jeweils aktivierte locale verwendet wird:

• lib/include/html_head.inc.php
• templates/layouts/base.php
• templates/layouts/base_without_infobox.php

Diese Seiten binden auch automatisch die oben erwähnte JavaScript-Bibliothek l10n.js ein.

JavaScript-API

Die offizielle JavaScript-Client-API enthält die Methode Object#toLocaleString, die wie folgt definiert ist:

Für Strings ruft diese Methode String#toString auf. An dieser Stelle setzt die Bibliothek an und definiert die vorhandene Methode um.

Wenn man jetzt also einen String in JavaScript übersetzen möchte, ruft man lediglich toLocaleString auf.

Beispiel:

var aString = "suchen".toLocaleString();

// ergibt bei aktiviertem locale de_DE: 
// aString === "suchen"

// ist hingegen en_GB aktiv:
// aString === "search"

Es werden lediglich die Strings übersetzt, die in der Liste des Web-Services enthalten sind. Nicht enthaltene bleiben, wie sie sind.

Neue Strings aufnehmen

Neue Strings können einfach über die oben genannte String.toLocaleString()-Methode im JavaScript ausgezeichnet werden. Anschliessend sollte das CLI-Skript extract-js-localizations.php angestossen werden, welche diese Strings extrahier und in die Datei app/views/localizations/show.php schreibt. Dadurch steht der Übersetzungsmechanismus auch für diese Strings bereit.