Service ScriptForge.L10N

De service bevat een aantal methoden gerelateerd met de vertaling van teksten van de applicatie en zou geen gevolgen moeten hebben voor de werking van de applicatie. De methoden in de service L10N worden hoofdzakelijk gebruikt voor:

Het aanmaken van POT-bestanden, met een POT-bestand kan een vertaler aan de slag om alle teksten in de applicatie te gaan vertalen vanuit standaard het Engels naar de gewenste taal.
Het op runtime ophalen van een tekst in de taal die in de eigenschap Locale is aangegeven.

De afkorting L10N staat voor 'Localization' en het is een aantal procedures voor het vertalen van teksten in een applicatie naar de taal van een specifiek land of regio.

PO-bestanden worden al heel lang in de 'free software community' gebruikt voor het kunnen aanbieden van een gebruikersinterface van een applicatie in de taal van de gebruiker zelf, dezelfde applicatie kan dan in alle talen waarvoor een vertaling is gemaakt, worden gebruikt. Een PO-bestand is een leesbaar gestructureerd tekstbestand waarin voor één taal per tekst in de brontaal (Engels) de gewenste vertaling wordt gegeven. Meestal zijn er voor een vertaling dan een heel stel PO-bestanden, een per onderdeel van de applicatie. Voor elke ondersteunde taal zijn er PO-bestanden, die uit de POT-bestanden per vertaling worden gegenereerd.

Het voordeel hiervan is dat het programmeren wordt gescheiden van het vertalen. Een POT-bestand wordt per versie gegenereerd uit de gemaakte code en het wordt vervolgens per gewenste taal omgezet naar een PO-bestand waarbij al vertaalde en nog gebruikte teksten worden overgenomen, zodat de vertalers aan de slag kunnen om de gewijzigde en nieuwe teksten te vertalen.

De service L10N is gebaseerd op de GNU-implementatie van PO-bestanden (portable object). Meer informatie over PO-bestanden.

De service heeft de onderstaande methoden:

AddText: Gebruikt door de programmeur om een verzameling later te vertalen teksten te maken.
AddTextsFromDialog: Verzamelt alle teksten in een instantie van een dialoogvenster.
ExportToPOTFile: Exporteert alle teksten die met AddText zijn verkregen, naar een POT-bestand.
GetText: Haalt op runtime de vertaling van een tekst op.

Met de eerste twee methoden kan door de programmeur worden bepaald welke teksten vertaald moeten worden en dus in het POT-bestand moeten komen. Maar het is niet verplicht om ze te gebruiken. Het POT-bestand kan ook anders worden gemaakt of bewerkt, bijvoorbeeld in een tekstverwerker.

Service aanroep

Voordat de service L10N gebruikt kan worden, moet de bibliotheek ScriptForge eerst worden geladen of geïmporteerd:

• Basic macro's kunnen de bibliotheek ScriptForge laden met de instructie:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Python scripts kunnen de module scriptforge importeren met:
from scriptforge import CreateScriptService

Het aanroepen van de service L10N kan op verschillende manieren, maar er zijn vijf argumenten die meegegeven kunnen worden, de map waar de PO-bestanden staan, de gewenste taal (locale), de gebruikte codering (encode), een PO-bestand waarop terug kan worden gevallen als een vertaling ontbreekt en de codering van dat bestand.

Syntaxis:

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

foldername: De map waarin de PO-bestanden staan. De naamgeving is volgens de FileSystem.FileNaming notatie.

locale: Een tekst als "nl-NL" (de locale voor Nederland), het kan ook "nl" zijn (de taal zonder het land).

encoding: De gebruikte karakterset. De standaardcodering is "UTF-8".

locale2: Een tekst die aangeeft wat de locale is van het bestand waarop teruggevallen moet worden als het PO-bestand van de locale ontbreekt.

encoding2: De gebruikte karakterset in locale2. De standaardcodering is "UTF-8".

Ga voor meer informatie over de namen van karaktersets naar IANA's Character Set-pagina. Houd er rekening mee dat LibreOffice niet alle bestaande tekensets implementeert.

Voorbeeld:

In BASIC

In dit voorbeeld ziet u een aanroep van de service L10N zonder optionele argumenten. Hiermee worden alleen de methoden AddText en ExportToPOTFile ingeschakeld, wat genoeg is om een POT-bestand aan te maken.


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

Vervolgens geven we de map aan waar de PO-bestanden staan. Omdat de locale nog niet is aangegeven wordt door de service de waarde die in de gebruikersinterface van LibreOffice gedefinieerd is, gebruikt, dat is dezelfde waarde als aangegeven in de eigenschap OfficeLocale van de service Platform.


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

In bovenstaande voorbeeld treedt bij uitvoeren een fout op als het PO-bestand van de locale OfficeLocale in de aangegeven map ontbreekt.

In onderstand voorbeeld wordt als locale gekozen voor Belgisch Frans ("fr-BE"), de service zal het bestand "fr-BE.po" in de map "C:\myPOFiles" proberen te gebruiken. Als dat bestand ontbreekt dan treedt er een fout op.


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

Om deze fout te voorkomen kan er een andere locale worden opgegeven waarop dan wordt terug gevallen. In dit voorbeeld wordt weer "fr-BE.po" geladen, maar als dat bestand niet bestaat dan wordt "en-US.po" geladen en gebruikt.


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

In de naam van een PO-bestand wordt altijd eerst de taal en dan meestal het land aangegeven. Voorbeelden zijn: "en-US.po", "fr-BE.po" en "fr.po".

Het wordt aanbevolen om bronnen na gebruik vrij te geven:


      Set myPO = myPO.Dispose()

In Python

Als we bovenstaande voorbeelden vertalen naar Python:


      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()

U kunt meerdere instanties van de service L10N service starten, maar elke instantie moet dan wel zelf een eigen map voor PO-bestanden gebruiken.

Eigenschappen

Naam	AlleenLezen	Type	Beschrijving
Folder	Ja	String	De map met de PO_bestanden (Eigenschap voor de notatie: FileSystem.FileNaming).
Languages	Ja	Array	Een zero-based matrix met alle namen (zonder de extensie "po") van de PO-bestanden in de gespecificeerde map Folder.
Locale	Ja	String	De nu actieve locale. Deze eigenschap is initieel niet gevuld als de service is aangeroepen zonder een van de optionele argumenten.

De methoden in de service L10N
AddText AddTextsFromDialog	ExportToPOTFile	GetText

AddText

Voegt een nieuwe te vertalen tekst toe aan de lijst met te vertalen teksten. De tekst moet niet al voorkomen als te vertalen tekst.

De methode retourneert True als het toevoegen lukt.

Syntaxis:

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

Parameters:

context: In een PO-bestand kan een onderverdeling van de teksten worden gemaakt in een soort groepen, bijvoorbeeld de tekst is een land. Dit wordt dan bij het opzoeken van de vertaling met de methode GetText weer gebruikt. De standaardwaarde is "".

msgid: De onvertaalde tekst zoals de tekst voorkomt in de programmacode. De tekst is verplicht. Vanzelfsprekend wordt msgidgebruikt om later de vertaalde tekst op te halen via de methode GetText samen met de context.

De tekst van msgid kan placeholders bevatten (%1 %2 %3 ...), deze worden dan bij uitvoering door het programma gebruikt om een aantal, een naam o.i.d. te tonen.

comment: Dit is een optioneel argument waarmee de programmeur een hint kan geven aan de vertalers wat er met de te vertalen tekst bedoeld wordt.

Voorbeeld:

In dit voorbeeld maken we wat te vertalen teksten, die altijd in het Engels zijn, aan:

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

Haalt automatisch de teksten uit een dialoog en voegt ze toe aan een lijst met te vertalen teksten. De volgende teksten worden gepakt:

De naam van de dialoog.
De 'caption' van de gebruikte elementen: Button, CheckBox, FixedLine, FixedText, GroupBox en RadioButton.
Statische teksten in ListBoxes en ComboBoxes.
Helpteksten en teksten die gebruikt worden als de gebruiker met de muis over een veld heengaat.

De methode retourneert True als de actie lukt.

Het dialoogvenster waaruit de teksten worden gehaald, moet op het moment van aanroepen van deze methode niet geopend zijn.

Indien de instantie van de service L10N wordt aangemaakt van een bestaand PO-bestand, gebruik dan de methode GetTextsFromL10N van de service Dialog om automatisch alle vertaalde teksten te laden in de dialoog.

Syntaxis:

svc.AddTextsFromDialog(dialog: svc): bool

Parameters:

dialog: Een instantie van de service die overeenkomt met de dialoog waar de teksten uit worden gehaald.

Voorbeeld:

In dit voorbeeld worden de teksten uit de dialoog "MyDialog" in de bibliotheek "Standard" gehaald en geëxporteerd naar een POT-bestand:

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

Exporteert een set onvertaalde tekenreeksen als een POT-bestand.

Om een reeks tekenreeksen te bouwen, kunt u ofwel een opeenvolging van AddText methodeaanroepen gebruiken, of door een succesvolle aanroep van de service L10N met als argument mapnaam. Het is ook mogelijk om een combinatie van beide technieken te gebruiken.

De methode retourneert True indien succesvol.

Syntaxis:

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

Parameters:

filename: De volledige naam van het uitvoerbestand in de notatie FileSystem.FileNaming.

header: Opmerkingen die bovenop het gegenereerde POT-bestand worden toegevoegd.

Gebruik geen leidende "#"-tekens. Als u wilt dat de koptekst wordt opgesplitst in meerdere regels, voegt u waar relevant escape-reeksen (\n) in. Er wordt een standaardkoptekst toegevoegd naast de tekst die is opgegeven in het argument header.

encoding: De tekenset die moet worden gebruikt (standaard = "UTF-8").

Voorbeeld:


       ' 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')

Het gegenereerde bestand moet de GNU-opdracht msgfmt --check met succes doorstaan.

GetText

Haalt de vertaalde tekenreeks op die overeenkomt met het gegeven argument msgid.

Er kan een lijst met argumenten worden opgegeven om de placeholders (%1, %2, ...) in de tekenreeks te vervangen.

Als er geen vertaalde tekenreeks wordt gevonden, retourneert de methode de niet-vertaalde tekenreeks na vervanging van de placeholders door de opgegeven argumenten.

Syntaxis:

Deze methode kan worden aangeroepen met de volledige naam GetText of met de sneltoets _ (een enkel onderstrepingsteken):

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

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

In de ScriptForge-bibliotheek zijn alle methoden die beginnen met het teken "_" alleen voor intern gebruik. De sneltoets _ die wordt gebruikt voor GetText is de enige uitzondering op deze regel en kan daarom veilig worden gebruikt in Basic- en Python-scripts.

Parameters:

msgid: De onvertaalde tekenreeks, de tekst die in de programmacode wordt weergegeven. Het mag niet leeg zijn. Het kan een willekeurig aantal placeholders bevatten (%1 %2 %3 ...) die kunnen worden gebruikt om tijdens runtime dynamisch tekst in te voegen.

Naast het gebruik van een enkele tekenreeks msgstr, accepteert deze methode ook de volgende indelingen:

De context tekenreeks waarmee de methode de msgid in het PO-bestand zal ophalen, of;
Een combinatie context|msgid, die de methode instrueert om de msgid op te halen met behulp van de gespecificeerde context-waarde. Met de context worden de woorden in groepen onderverdeeld, zo kan er verschil worden gemaakt tussen woorden met meerdere betekenissen.

args: Waarden die de placeholders vervangen. Elk type variabele is toegestaan, maar alleen tekenreeksen, getallen en datums worden in aanmerking genomen.

Voorbeeld:

In BASIC

Overweeg dat de volgende code wordt uitgevoerd op een LibreOffice-installatie met de landinstelling ingesteld op "es-ES". Bovendien is er een bestand "es-ES.po" in de opgegeven map dat de tekenreeks vertaalt die is doorgegeven aan de methode GetText:


      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-routines of variabelen die beginnen met een underscore "_" zijn voor intern gebruik. Gebruik deze niet in een Basic of Python-macro.

ScriptForge.FileSystem-service

Vertaling van besturingselementen in de dialoogeditor