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

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 angeben, 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 angibt, 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 gibt den Ordner an, 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 anzugeben. 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("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.


Bitte unterst├╝tzen Sie uns!