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:

note

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 angibt.

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.

tip

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:

note

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

Um den Dienst L10N aufzurufen, können zwei optionale Argumente angegeben werden, um den Ordner zu bestimmen, in dem sich PO-Dateien befinden, und die zu verwendende Ländereinstellung, wie unten beschrieben.

Syntax:

CreateScriptService("L10N", foldername: str, locale: str): 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).

note

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


Beispiel:

In Basic

Das folgende Beispiel instanziiert den Dienst L10N ohne optionale Argumente. Dadurch werden nur die Methoden AddText und ExportToPOTFile aktiviert.


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

Das folgende Beispiel gibt den Ordner an, der die PO-Dateien enthält. Da das Gebietsschema nicht definiert ist, verwendet die Dienstinstanz die aktuellen LibreOffice-Gebietsschemaeinstellungen.


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

Das obige Beispiel führt zu einem Laufzeitfehler, wenn die PO-Datei für das aktuelle Gebietsschema nicht im angegebenen Ordner vorhanden ist.


Im folgenden Beispiel sind sowohl der Ordnername als auch die Gebietsschemaeinstellungen explizit als belgisches Französisch definiert.


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

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 = myPO.Dispose()
    

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:

Die Methode gibt bei Erfolg True zurück.

note

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("en-US.pot")
    
In Python

      dlg = CreateScriptService("Dialog", "GlobalScope", "Standard", "Dialog1")
      myPO = CreateScriptService("L10N")
      myPO.AddTextsFromDialog(dlg)
      myPO.ExportToPOTFile("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: Die Ausgabedatei in der Notation von FileSystem.FileNaming.

header: Kommentare, die über der generierten 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("myFile.pot", Header := "First line of the header\nSecond line of the header")
    

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

Die generierte 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

note

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:

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 LibreOffice-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"
    
warning

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.