Übersetzungen auf Basis von Text-IDs

Der Übersetzungsmechanismus auf Basis von Text-IDs ist ein leistungsstarkes System für Internationalisierung und Lokalisierung. Jeder Text in der Anwendung verfügt über eine eindeutige Kennung (Text-ID), die Sie im Quellcode anstelle des eigentlichen Textes verwenden. Dies erleichtert die Verwaltung großer Mengen übersetzter Texte erheblich.

Internationalisierung mit Text-IDs

Bei der Verwendung von Text-IDs anstelle von einfachem Text ist die allgemeine Vorgehensweise zur Internationalisierung einer Anwendung dieselbe, die Details unterscheiden sich jedoch geringfügig:

1. Die Funktionen und Makros für das auf Text-IDs basierende Übersetzungssystem unterscheiden sich von denen des Systems mit einfachem Text. Sie verwenden die Funktion `qsTrId()` anstelle von `qsTr()`, das Makro ` QT_TRID_NOOP()` anstelle von ` QT_TR_NOOP()` und das Makro ` QT_TRID_N_NOOP()` anstelle von ` QT_TR_N_NOOP()`.
2. Verwenden Sie Text-IDs anstelle von Klartext-Strings als Zeichenfolgen in der Benutzeroberfläche. Zum Beispiel: qsTrId("id-back-not-front")
3. Sie können keinen Kontextparameter mit einer Text-ID angeben; daher benötigen identisch geschriebene Wörter mit unterschiedlicher Bedeutung separate Text-IDs. Beispielsweise unterscheidet „ qsTrId("id-back-backstep") “ den Rückschritt „Back“ vom „ id-back-not-front “ „Back“.
4. Da Kontextnamen für text-ID-basierte Übersetzungen nicht zulässig sind, listet „ Qt Linguist “ die IDs in einer Datei ohne Kontextnamen auf.
5. Der technische englische Text, den Sie in der Benutzeroberfläche für Entwicklungsversionen sehen, wird durch einen Kommentar von //% gekennzeichnet. Wenn Sie diesen nicht einfügen, wird die Text-ID in der Benutzeroberfläche angezeigt. Dies ist besonders wichtig, wenn Sie Texte mit Parametern haben. Der Kommentar von //% muss die Parameterkennungen in die Zeichenfolge aufnehmen. Zum Beispiel: //% "Number of files: %1"
6. Die „ //: “-Kommentare, die dem Übersetzer zusätzliche Informationen liefern, sind im Klartext-System optional. Beim text-ID-basierten System sind diese zusätzlichen Informationen jedoch unerlässlich, da Sie ohne sie nur über die Text-ID verfügen und der Übersetzer ohne weiteren Kontext möglicherweise keine sinnvolle Übersetzung erstellen kann. Man kann lange, beschreibende Text-IDs ohne Kommentare verwenden, doch Kommentare sind oft leichter zu verstehen.

Die folgenden nebeneinander angeordneten Codeausschnitte zeigen einen Vergleich zwischen text-ID-basierten und Klartext-basierten Übersetzungen:

Text {
    id: backTxt;
    //: The back of the object, not the front
    //% "Back"
    //~ Context Not related to back-stepping
    text: qsTrId("id-back-not-front");
}

Text {
    id: backTxt;
    //: The back of the object, not the front
    //~ Context Not related to back-stepping
    text: qsTr("Back","Not front")
}

Lokalisierung mit Text-IDs

Die Lokalisierung mit Text-IDs erfolgt weitgehend nach dem gleichen Verfahren wie bei Klartext.

Sie verwenden das Tool „lupdate“, um die TS-Dateien zu generieren, in die Sie die Übersetzungen einfügen. Die Quellwerte in den Übersetzungsdateien sind Text-IDs statt Klartext. Daher benötigen Sie entweder aussagekräftige Text-IDs oder aussagekräftige zusätzliche Kommentare – oder beides –, um sicherzustellen, dass die Übersetzungen korrekt sind.

Der oben angeführte Beispieltext für eine auf Text-IDs basierende Benutzeroberfläche führt zu folgendem Inhalt in der .ts-Datei:

<message id="id-back-not-front">
    <source>Back</source>
    <extracomment>The back of the object, not the front</extracomment>
    <translation type="unfinished"></translation>
    <extra-Context>Not related to back-stepping</extra-Context>
</message>

Wenn für einen bestimmten Text keine Übersetzung verfügbar ist (was in der Regel bis zu einem späten Entwicklungsstadium der Fall ist), wird in der Benutzeroberfläche anstelle des eigentlichen Textes die Text-ID angezeigt. Um die Anwendung für Testzwecke benutzerfreundlicher zu gestalten, können Sie „ lrelease “ so einrichten, dass der Quelltext in „Engineering English“ (aus den Kommentaren „ //% “) als übersetzter Text verwendet und mit einem Kennzeichen, beispielsweise einem Ausrufezeichen (!), markiert wird, damit Sie Texte erkennen können, die noch nicht übersetzt sind.

Gruppierung von ID-basierten Übersetzungen

Sie können jeder ID-basierten Übersetzung eine Bezeichnung zuweisen, um ID-basierte Einträge großer Projekte in kleinere Gruppen zu organisieren. Um einem ID-basierten Eintrag eine Bezeichnung zuzuweisen, fügen Sie einen „ //@ “-Kommentar hinzu, in dem Sie die Bezeichnung angeben, zum Beispiel in C++:

//% "Open file"
//@ FileOperations
qtTrId("msg.open");

Oder in QML:

//% "Open file"
//@ FileOperations
qsTrId("msg.open");

Wenn Sie die TS-Datei in Qt Linguist, werden die ID-basierten Einträge mit demselben Label zusammengefasst, ähnlich wie textbasierte Einträge, die nach Kontext gruppiert werden. Alle Elemente ohne Label erscheinen unter „ <unnamed label> “.

Automatische Label-Generierung

Anstatt Bezeichnernamen manuell anzugeben, können Sie Platzhalter verwenden, um Bezeichnungen automatisch auf Basis der Codestruktur zu generieren:

• //@ <context> - Verwendet automatisch den vollständigen Kontext (Namespace::Klasse)
• //@ <class> - Verwendet automatisch nur den Klassennamen (ohne Namespaces)
• //@ <file> - Verwendet automatisch den Quelldateinamen

Kombinieren von Platzhaltern

Platzhalter können mit benutzerdefiniertem Text kombiniert werden, um aussagekräftigere Bezeichnungen zu erstellen:

• //@ <file>:<class> - Kombiniert Dateiname und Klasse: filehandler.cpp:FileHandler
• //@ <context>_customSuffix - Fügt ein Suffix hinzu: MyApp::FileHandler_customSuffix
• //@ module_<file>_<class>-label - Benutzerdefiniertes Präfix und Suffix: module_filehandler.cpp_FileHandler-label
• //@ <context>:<file> - Kontext mit Datei: MyApp::FileHandler:filehandler.cpp

Beispiel in C++:

namespace MyApp {
class FileHandler : QObject {
    Q_OBJECT
    void open() {
        //% "Open file"
        //@ <context>
        qtTrId("msg.open"); // Label: MyApp::FileHandler

        //% "Save file"
        //@ <class>
        qtTrId("msg.save"); // Label: FileHandler

        //% "Export"
        //@ <file>
        qtTrId("msg.export"); // Label: filehandler.cpp
    }
};
}

Oder in QML:

Item {
    id: myComponent
    Component.onCompleted: {
        //% "Loading"
        //@ <context>
        qsTrId("msg.loading") // Label: <component-name>

        //% "Ready"
        //@ <file>
        qsTrId("msg.ready") // Label: main.qml

        //% "Initialized"
        //@ <file>:<context>-state
        qsTrId("msg.init") // Label: main.qml:<component-name>-state
    }
}

Automatische Bezeichnungen sind besonders in großen Projekten nützlich, in denen die manuelle Verwaltung von Bezeichnungen über viele Dateien hinweg mühsam sein kann. Sie gewährleisten eine konsistente Gruppierung auf Basis der Codestruktur und geben Übersetzern Hinweise darauf, wo die Übersetzung verwendet wird.

CMake-Konfiguration

Verwenden Sie beim Erstellen mit CMake das Präfix qml_ für .ts-Dateien. Beispiel: qml_en.ts. Fügen Sie in der Datei „CMakeLists.txt“ die Funktion `qt_add_translations` hinzu, in der Sie die *.ts-Dateien als Werte von ` TS_FILES` auflisten, und setzen Sie den Wert von `RESOURCE_PREFIX` auf die URI der Datei „main.qml“ des Projekts, gefolgt von `/i18n`:

qt_add_translations(${CMAKE_PROJECT_NAME}
    TS_FILES i18n/qml_de_DE.ts i18n/qml_en_US.ts
    RESOURCE_PREFIX Main/i18n
)

Erweiterte Verwendung mit qmake

Bei Projekten, die auf eine große Anzahl von Sprachumgebungen abzielen, können Sie die TRANSLATIONS-Angaben aus der .pro-Datei entfernen und die Übersetzungen stattdessen mit einem separaten Skript verwalten. Das Skript kann für jedes der gewünschten Ziele die Befehle lrelease und lupdate aufrufen.

Die Aktualisierungen könnten etwa wie folgt per Skript durchgeführt werden:

lupdate -recursive <project-dir> -ts <project-dir>/i18n/myapp-text_en_GB.ts
lupdate -recursive <project-dir> -ts <project-dir>/i18n/myapp-text_en_US.ts
...

Die Erstellung der endgültigen .qm-Dateien könnte etwa wie folgt in einem Skript umgesetzt werden:

lrelease <project-dir>/i18n/myapp-text_en_GB.ts
lrelease <project-dir>/i18n/myapp-text_en_US.ts
...