Dienst ScriptForge.L10N

Dieser Dienst bietet eine Reihe von Methoden zur Übersetzung von Zeichenfolgen mit minimaler Auswirkung auf den Quellcode des Programms. Die vom Dienst L10N bereitgestellten Methoden können hauptsächlich für Folgendes verwendet werden:

Erstellen von POT-Dateien, die als Vorlagen für die Übersetzung aller Zeichenfolgen im Programm verwendet werden können.
Um zur Laufzeit übersetzte Zeichenfolgen für die Sprache zu erhalten, die in der Eigenschaft Locale festgelegt ist.

Das Akronym L10N steht für Lokalisierung und bezieht sich auf eine Reihe von Verfahren zur Übersetzung von Software in ein bestimmtes Land oder eine bestimmte Region.

PO-Dateien werden seit langem in der Gemeinschaft freier Software als Mittel zur Bereitstellung mehrsprachiger Benutzeroberflächen beworben. Dies wird durch die Verwendung von für Menschen lesbare Textdateien mit einer gut definierten Struktur erreicht, die für jede gegebene Sprache die Zeichenfolge der Ausgangssprache und die lokalisierte Zeichenfolge festlegt.

Der Hauptvorteil des PO-Formats ist die Trennung von Programmierer und Übersetzer. PO-Dateien sind unabhängige Textdateien, sodass der Programmierer POT-Vorlagendateien an Übersetzer senden kann, die dann ihren Inhalt übersetzen und die übersetzten PO-Dateien für jede unterstützte Sprache zurücksenden.

Der Dienst L10N basiert auf der GNU-Implementierung von PO-Dateien (Portable Object). Um mehr über dieses Dateiformat zu erfahren, besuchen Sie GNU gettext Utilities: PO Files.

Dieser Dienst implementiert die unten aufgeführten Methoden:

AddText: Wird vom Programmierer verwendet, um eine Reihe von Zeichenfolgen zu erstellen, die später übersetzt werden.
AddTextsFromDialog: Extrahiert alle Zeichenfolgen aus einer Dienstinstanz Dialog.
ExportToPOTFile: Exportiert die durch die Methode AddText hinzugefügten Zeichenfolgen in eine POT-Datei.
GetText: Holt die übersetzten Zeichenfolgen zur Laufzeit.

Beachten Sie, dass die ersten beiden Methoden verwendet werden, um einen Satz übersetzbarer Zeichenfolgen zu erstellen und sie in eine POT-Datei zu exportieren. Es ist jedoch nicht zwingend erforderlich, POT-Dateien mit diesen Methoden zu erstellen. Da es sich um Textdateien handelt, hätte der Programmierer sie mit einem beliebigen Texteditor erstellen können.

Dienstaufruf

Vor der Verwendung des Dienstes L10N muss die Bibliothek ScriptForge geladen oder importiert werden:

• Grundlegende Makros erfordern das Laden der Bibliothek ScriptForge mit der folgenden Anweisung:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Python-Skripte erfordern einen Import aus dem Modul scriptforge:
from scriptforge import CreateScriptService

Es gibt mehrere Möglichkeiten, den Dienst L10N mit bis zu fünf optionalen Argumenten aufzurufen, die den Ordner festlegen, in dem PO-Dateien gespeichert sind, das Gebietsschema und die zu verwendende Codierung sowie eine Fallback-PO-Datei und ihre Codierung.

Syntax:

CreateScriptService("L10N", opt foldername: str, opt locale: str, encoding: str = "UTF-8", opt locale2: str, encoding2: str = "UTF-8"): svc

foldername: Der Ordner, der die PO-Dateien enthält. Es muss in der Notation von FileSystem.FileNaming ausgedrückt werden.

locale: Eine Zeichenfolge in der Form "la-CO" (Sprache-LAND) oder in der Form "la" (Sprache).

encoding: Der zu verwendende Zeichensatz. Die Standardcodierung ist „UTF-8“.

locale2: Eine Zeichenfolge, welche das Fallback-Gebietsschema festlegt, das verwendet werden soll, falls die PO-Datei, die dem Gebietsschema entspricht, das im Parameter locale definiert ist, nicht existiert. Dieser Parameter wird in der Form "la-CO" (Sprache-LAND) oder "la" (Sprache) ausgedrückt.

encoding2: Der Zeichensatz der Fallback-PO-Datei, die dem Argument locale2 entspricht. Die Standardcodierung ist „UTF-8“.

Um mehr über die Namen von Zeichensätzen zu erfahren, besuchen Sie die Seite IANA's Character Set. Beachten Sie, dass Collabora Office nicht alle vorhandenen Zeichensätze implementiert.

Beispiel:

In Basic

Das folgende Beispiel instanziiert den Dienst L10N ohne optionale Argumente. Dadurch werden nur die Methoden AddText und ExportToPOTFile aktiviert, was zum Erstellen von POT-Dateien nützlich ist.


      GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
      Dim myPO As Variant
      Set myPO = CreateScriptService("L10N")

Das folgende Beispiel legt den Ordner fest, der die PO-Dateien enthält. Da das Gebietsschema nicht definiert ist, verwendet die Dienstinstanz das Gebietsschema, das für die Collabora Office-Benutzeroberfläche definiert ist. Dies ist dasselbe Gebietsschema, das in der Eigenschaft OfficeLocale des Dienstes Platform definiert ist.


      Set myPO = CreateScriptService("L10N", "C:\myPOFiles")

Das obige Beispiel führt zu einem Laufzeitfehler, wenn die PO-Datei, die dem Gebietsschema OfficeLocale entspricht, nicht im angegebenen Ordner vorhanden ist.

Im Beispiel unten ist das Gebietsschema ausdrücklich als belgisches Französisch („fr-BE“) definiert, daher lädt der Dienst die Datei „fr-BE.po“ aus dem Ordner „C:\myPOFiles“. Wenn die Datei nicht existiert, tritt ein Fehler auf.


      Set myPO = CreateScriptService("L10N", "C:\myPOFiles", "fr-BE", "UTF-8")

Um Fehler zu vermeiden, ist es möglich, ein bevorzugtes und ein Fallback-Gebietsschema und eine -Kodierung festzulegen. Im folgenden Beispiel wird zunächst versucht, die Datei „fr-BE.po“ aus dem angegebenen Ordner zu laden, und falls diese nicht existiert, wird die Datei „en-US.po“ geladen.


      Set myPO = CreateScriptService("L10N", "C:\myPOFiles", "fr-BE", "UTF-8", "en-US", "UTF-8")

PO-Dateien müssen in der Form „la-CO.po“ oder „la.po“ benannt werden, wobei sich „la“ auf die Sprache und „CO“ auf das Land bezieht. Einige Beispiele sind: „en-US.po“, „fr-BE.po“ oder „fr.po“.

Es wird empfohlen, Ressourcen nach der Verwendung freizugeben:


      Set myPO = myPO.Dispose()

In Python

Die obigen Beispiele können wie folgt in Python übersetzt werden:


      from scriptforge import CreateScriptService
      myPO = CreateScriptService('L10N')


      myPO = CreateScriptService('L10N', r'C:\myPOFiles')


      myPO = CreateScriptService('L10N', r'C:\myPOFiles', 'fr-BE')


      myPO = CreateScriptService('L10N', r'C:\myPOFiles', 'fr-BE', 'UTF-8', 'en-US', 'UTF-8')
      myPO = myPO.Dispose()

Mehrere Instanzen des Dienstes L10N können koexistieren. Jede Instanz muss jedoch ein separates Verzeichnis für ihre PO-Dateien verwenden.

Eigenschaften

Name	Schreibgeschützt	Typ	Beschreibung
Folder	Ja	String	Der Ordner mit den PO-Dateien (siehe die Eigenschaft FileSystem.FileNaming, um mehr über die verwendete Notation zu erfahren).
Languages	Ja	Array	Eine nullbasierte Matrix, die alle Basisnamen (ohne die Erweiterung ".po") der PO-Dateien auflistet, die im angegebenen Ordner gefunden wurden.
Locale	Ja	String	Die derzeit aktive Sprach-LAND-Kombination. Diese Eigenschaft ist zunächst leer, wenn der Dienst ohne eines der optionalen Argumente instanziiert wurde.

Liste der Methoden im Dienst L10N
AddText AddTextsFromDialog	ExportToPOTFile	GetText

AddText

Fügt einen neuen Eintrag der Liste der lokalisierbaren Zeichenfolgen hinzu. Er darf noch nicht existieren.

Die Methode gibt bei Erfolg True zurück.

Syntax:

svc.AddText(context: str = '', msgid: str = '', comment: str = ''): bool

Parameter:

context: Der Schlüssel zum Abrufen der übersetzten Zeichenfolge mit der Methode GetText. Dieser Parameter hat den Standardwert "".

msgid: Die unübersetzte Zeichenfolge, die der Text ist, der im Programmcode erscheint. Sie darf nicht leer sein. msgid wird zum Schlüssel zum Abrufen der übersetzten Zeichenfolgen über die Methode GetText, wenn context leer ist.

msgid kann beliebig viele Platzhalter (%1 %2 %3 …) enthalten, um die Zeichenfolgen zur Laufzeit dynamisch zu verändern.

comment: Optionaler Kommentar, welcher der Zeichenfolge hinzugefügt werden kann, um Übersetzern zu helfen.

Beispiel:

Das folgende Beispiel erstellt eine Reihe von Zeichenfolgen in Englisch:

In Basic


      myPO.AddText(, "This is a string to be included in a POT file")
      myPO.AddText("CTX1", "A string with a context")
      myPO.AddText(, "Provide a String value", Comment := "Do not translate the word String")

In Python


      myPO.AddText(msgid = 'This is a string to be included in a POT file')
      myPO.AddText('CTX1', 'A string with a context')
      myPO.AddText(msgid = 'Provide a String value', comment = 'Do not translate the word String')

AddTextsFromDialog

Extrahiert automatisch Zeichenfolgen aus einem Dialog und fügt sie der Liste der lokalisierbaren Textzeichenfolgen hinzu. Die folgenden Zeichenfolgen werden extrahiert:

Der Titel des Dialogs.
Die Beschriftung der folgenden Steuerelementtypen: Schaltfläche, Markierfeld, Geschützte Linie, Beschriftungsfeld, Gruppenfeld und Optionsfeld.
Statische Zeichenfolgen in Listenfeldern und Kombinationsfeldern.
Der Hilfetext, der angezeigt wird, wenn die Maus über das Steuerelement bewegt wird.

Die Methode gibt bei Erfolg True zurück.

Der Dialog, aus dem Zeichenfolgen extrahiert werden sollen, darf beim Aufruf der Methode nicht geöffnet sein.

Wenn eine Dienstinstanz L10N aus einer vorhandenen PO-Datei erstellt wird, verwenden Sie die Methode GetTextsFromL10N aus dem Dienst Dialog, um automatisch alle übersetzten Zeichenfolgen in den Dialog zu laden.

Syntax:

svc.AddTextsFromDialog(dialog: svc): bool

Parameter:

dialog: eine Dienstinstanz "Dialog", die dem Dialog entspricht, aus dem Zeichenfolgen extrahiert werden.

Beispiel:

Das folgende Beispiel extrahiert alle in der Bibliothek "Standard" gespeicherten Zeichenfolgen aus dem Dialog "MyDialog" und exportiert sie in eine POT-Datei:

In Basic


      oDlg = CreateScriptService("Dialog", "GlobalScope", "Standard", "MyDialog")
      myPO = CreateScriptService("L10N")
      myPO.AddTextsFromDialog(oDlg)
      myPO.ExportToPOTFile("C:\en-US.pot")

In Python


      dlg = CreateScriptService("Dialog", "GlobalScope", "Standard", "Dialog1")
      myPO = CreateScriptService("L10N")
      myPO.AddTextsFromDialog(dlg)
      myPO.ExportToPOTFile("C:\en-US.pot")

ExportToPOTFile

Exportiert einen Satz nicht übersetzter Zeichenfolgen als POT-Datei.

Um einen Satz von Zeichenfolgen zu erstellen, können Sie entweder eine Reihe von Aufrufen der Methode AddText verwenden oder einen erfolgreichen Aufruf des Dienstes L10N mit dem vorhandenen Argument foldername. Es ist auch möglich, eine Kombination beider Techniken zu verwenden.

Die Methode gibt bei Erfolg True zurück.

Syntax:

svc.ExportToPOTFile(filename: str, header: str = '', encoding:str = 'UTF-8'): bool

Parameter:

filename: Der vollständige Name der Ausgabedatei in der Notation FileSystem.FileNaming.

header: Kommentare, die über der erzeugten POT-Datei hinzugefügt werden.

Verwenden Sie keine führenden Zeichen „#“. Wenn Sie möchten, dass der Header in mehrere Zeilen aufgeteilt wird, fügen Sie gegebenenfalls Escape-Sequenzen (\n) ein. Ein Standard-Header wird neben dem im Argument header angegebenen Text hinzugefügt.

encoding: Der zu verwendende Zeichensatz (Standard = "UTF-8").

Beispiel:


       ' Basic
       myPO.ExportToPOTFile("C:\myFile.pot", Header := "First line of the header\nSecond line of the header")


      # Python
      myPO.ExportToPOTFile('C:\myFile.pot', header = 'First line of the header\nSecond line of the header')

Die erzeugte Datei sollte den GNU-Befehl msgfmt --check erfolgreich bestehen.

GetText

Ruft die übersetzte Zeichenfolge ab, die dem angegebenen Argument msgid entspricht.

Eine Liste von Argumenten kann angegeben werden, um die Platzhalter (%1, %2, …) in der Zeichenfolge zu ersetzen.

Wenn keine übersetzte Zeichenfolge gefunden wird, gibt die Methode die nicht übersetzte Zeichenfolge zurück, nachdem die Platzhalter durch die angegebenen Argumente ersetzt wurden.

Syntax:

Diese Methode kann entweder mit dem vollständigen Namen GetText oder mit der Abkürzung _ (ein einzelner Unterstrich) aufgerufen werden:

svc.GetText(msgid: str, args: any[0..*]): str

svc._(msgid: str, args: any[0..*]): str

In der Bibliothek ScriptForge sind alle Methoden, die mit dem Zeichen „_“ beginnen, nur für den internen Gebrauch reserviert. Die Abkürzung _, die für GetText verwendet wird, ist jedoch die einzige Ausnahme von dieser Regel, daher kann sie sicher in Basic- und Python-Skripten verwendet werden.

Parameter:

msgid: Die unübersetzte Zeichenfolge, die der Text ist, der im Programmcode erscheint. Sie darf nicht leer sein. Sie kann beliebig viele Platzhalter (%1 %2 %3 …) enthalten, die zum dynamischen Einfügen von Text zur Laufzeit verwendet werden können.

Neben der Verwendung einer einzelnen Zeichenfolge für msgid akzeptiert diese Methode auch die folgenden Formate:

Die Zeichenfolge context, mit der die Methode msgid in der PO-Datei abruft, oder;
Eine Kombination context|msgid, welche die Methode anweist, msgid unter Verwendung des angegebenen Wertes für context abzurufen. Der zweite Teil des Arguments wird verwendet, um die Lesbarkeit des Codes zu verbessern.

args: Werte, welche in die Platzhalter eingefügt werden sollen. Jeder Variablentyp ist erlaubt, es werden jedoch nur Zeichenfolgen, Zahlen und Datumsangaben berücksichtigt.

Beispiel:

In Basic

Stellen Sie sich vor, der folgende Code wird auf einer Collabora Office-Installation ausgeführt, wobei das Gebietsschema auf „es-ES“ festgelegt ist. Zusätzlich gibt es eine Datei "es-ES.po" im angegebenen Ordner, welche die an die Methode GetText übergebene Zeichenfolge übersetzt:


      myPO = CreateScriptService("L10N", "C:\myPOFiles\")
      myPO.GetText("Welcome %1! Hope you enjoy this program", "John")
      ' "¡Bienvenido John! Espero que disfrutes de este programa"

In Python


      myPO = CreateScriptService('L10N', r"C:\myPOFiles")
      myPO.GetText('Welcome %1! Hope you enjoy this program', 'John')
      # "¡Bienvenido John! Espero que disfrutes de este programa"

Alle ScriptForge Basic-Routinen oder Bezeichner, denen ein Unterstrich "_" vorangestellt ist, sind für den internen Gebrauch reserviert. Sie sind nicht für die Verwendung in Basic-Makros oder Python-Skripten vorgesehen.

Dienst ScriptForge.FileSystem

Übersetzen der Steuerelemente im Dialog-Editor