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

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

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

note

• 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“.

note

Um mehr über die Namen von Zeichensätzen zu erfahren, besuchen Sie die Seite IANA's Character Set. Beachten Sie, dass LibreOffice 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 LibreOffice-Benutzeroberfläche definiert ist. Dies ist dasselbe Gebietsschema, das in der Eigenschaft OfficeLocale des Dienstes Platform definiert ist.


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

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")
    
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 = CreateScriptService('L10N', r'C:\myPOFiles', 'fr-BE', 'UTF-8', 'en-US', 'UTF-8')
      myPO = myPO.Dispose()
    
note

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:

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("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 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("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')
    
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.


Bitte unterstützen Sie uns!