locale.xml

In der locale.xml können Sie Übersetzungen für Ihre Erweiterung von QUIQQER zur Verfügung stellen. Für beliebig viele Sprachen können hier Übersetzungen angelegt werden. Diese Übersetzungen stehen in PHP und JavaScript über das Locale Objekt zur Verfügung. Alle Übersetzungen, auch die von QUIQQER finden Sie in locale.xml Dateien. Diese Übersetzungen werden von QUIQQER in Datenbank Tabelle locale gespeichert. Über das Frontend sind diese Übersetzungen editierbar (auch export + import), die locale.xml Dateien werden dadurch nicht verändert. Weitere Informationen zum Editieren über das Frontend entnehmen Sie bitte der Benutzer Dokumentation.

Zusätzlich ist es möglich im Nachhinein Übersetzungen zu überschreiben ohne die locale.xml zu verändern.

Aufbau

Eine locale xml gliedert sich wie folgt:

<locales>
    <groups name="package/awesome" datatype="js">
        <locale name="my.translation.var.in.java.script">
            <de><![CDATA[Ich existiere nur in JavaScript]]></de>
            <en><![CDATA[I exist only in JavaScript]]></en>
        </locale>
    </groups>

    <groups name="package/awesome" datatype="php">
        <locale name="my.translation.var.in.java.script">
            <de><![CDATA[Ich existiere nur in PHP]]></de>
            <en><![CDATA[I exist only in PHP]]></en>
        </locale>
        <locale name="my.translation.var.in.java.script" html="true">
            <de><![CDATA[<p>ich kann html enthalten und <u>bin mit einem editor editierbar</u></p>]]></de>
            <en><![CDATA[<p>I can contain html and <u>i am edited with an editor</u></p>]]></en>
        </locale>
    </groups>

    <groups name="package/awesome" datatype="php,js">
        <locale name="my.translation.var.in.javascript.and.php">
            <de><![CDATA[Ich existiere in PHP und JavaScript]]></de>
            <en><![CDATA[I exist in PHP and JavaScript]]></en>
        </locale>
    </groups>
</locales>

<locales>
    <groups name="package/awesome" datatype="php,js">
        <locale name="my.translation.var.in.javascript.and.php" priority="3">
            <de><![CDATA[Ich existiere in PHP und JS und überschreibe noch die Variable my.translation.var.in.javascript.and.php ]]></de>
            <en><![CDATA[I exist in PHP and JS and override the variable my.translation.var.in.javascript.and.php]]></en>
        </locale>
    </groups>
</locales>

Erklärung

• <locales>: Anfang der locale Definition
• <groups>: Übersetzungsgruppe
• <locale>: Übersetzungsvariable

<groups name="my/group">

Das name Attribut ist ein Pflichtattribut. Dies definiert in welcher locale Gruppe die Variable existiert.

Das datatype Attribut ist optional. Dieses Attribut legt fest, in welchem Bereich die Variable existiert. D.h. ob die Variable über PHP und/oder JavaScript erreichbar ist.

Mögliche Werte:

• datatype="php" (default)
• datatype="js"
• datatype="php,js"

datatype wurde aus performance technischen Gründen integriert, damit nicht zu viele Objekte und Werte im JavaScript existieren. Das System kann somit für JavaScript eine eigens compilierte Übersetzungsdatei erstellen.

<locale name="my.translation.var">

Das name Attribut

In dem <locale> Node werden alle Übersetzungen der Variable mit einem Sprachkürzel definiert.

<de> = deutsch <en> = englisch

Den Inhalt einer Übersetzung bitte mit <![CDATA[ ]]> verwenden, damit es keine Probleme mit dem Inhalt gibt.

Übersetzung-Texte

Variablen

Im Übersetzung-Text können sogenannte Variablen verwendet werden, damit vom System Werte im Text platziert werden können. Dem Locale Objekt müssen diese Variablen im Programmcode natürlich übergeben werden.

Die Variablen können frei in die Sprachvariablen eingebunden werden. Hierzu muss der Variablenname einfach in eckigen Klammern platziert sein:

Beispiel:

<locale name="my.awesome.translation">
    <de><![CDATA[Mein Benutzername ist [username]]]></de>
    <en><![CDATA[My username is [username]]]></en>
</locale>

<?php

\QUI::getLocale()->get( 'my/group', 'my.awesome.translation', array(
    'username' => $User->getName()
));

?>

Html

In Übersetzungstexten kann HTMl verwendet werden. Hierfür muss lediglich das Attribut 'html' der Sprachvariablendefinition auf true gesetzt sein. Beispiel:

  <locale name="my.translation.var.in.java.script" html="true">
            <de><![CDATA[<p>ich kann html enthalten und <u>bin mit einem editor editierbar</u></p>]]></de>
            <en><![CDATA[<p>I can contain html and <u>i am edited with an editor</u></p>]]></en>
  </locale>

Zu beachten:
Mustache rendert HTML nur, wenn die Variable in drei geschweiften Klammern gesetzt ist. Beispiel : {{{variable_mit_html}}}

Zugriff auf Übersetzungen

In PHP und JavaScript gibt es jeweils ein QUIQQER Locale Objekt. In diesem Objekt wird automatisch die Umgebungssprache verwendet. Möchten Sie nun eine Variable nutzen geht dies wie folgt:

PHP

<?php

\QUI::getLocale()->get( 'my/group', 'my.translation.var' );

\QUI::getLocale()->get( 'my/group', 'my.translation.var', array(
    'param1' => $value,
    'param2' => $something
));

?>

JavaScript

require(['Locale'], function(Locale) 
{
    Locale.get( 'my/group', 'my.translation.var' );

    Locale.get( 'my/group', 'my.translation.var', {
        'param1' : value,
        'param2' : something
    });
});

HTML (Smarty)

QUIQQER/smarty liefert ein Smarty Plugin (Plugin Wiki) mit, welches erlaubt Übersetzungen direkt in Smarty Templates aufzurufen:

{locale group="my/group" var="my.translation.var"}

XML

<locale group="quiqqer/group" var="variable.name" />

Nutzung - Hinweis

Es macht Sinn sich an bestimmte Namenskonventionen zu halten, damit nicht ungewollt fremde Übersetzungen überschrieben werden. Daher sollten folgende Namenskonventionen für locale Gruppen und Variablen genutzt werden:

Gruppen

Für Pakete package/PACKAGE_NAME Für Projekte / Templates project/PROJECT_NAME Für das QUIQQER System system/quiqqer Für Zugriffsrechte locale/permissions

Beispiel:

<groups name="package/translator" type="php">

Variablen

Generell sollten aussagekräftige Namen verwendet werden. Es nutzt niemandem, wenn es Variablen wie "var.1", "var.2" oder "translate.var.10" gibt.

Für exceptions sollte die variable immer mit exception. beginnen und messages (Meldungen) immer mit message.

Beispiel:

<locale name="exception.no.quiqqer.update.archive">
    <de><![CDATA[Das Update konnte nicht durchgeführt werden. Das Archiv ist kein QUIQQER Archiv.]]></de>
    <en><![CDATA[The update is not possible. The archive is not a QUIQQER archive.]]></en>
</locale>