ScriptForge.L10N service

Inhoud
Index 🔎︎

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

## Het aanroepen van een service

To invoke the L10N service, two optional arguments can be specified to determine the folder where PO files are located and the locale to be used, as described below.

### Syntaxis:

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

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

### Voorbeeld:

##### In BASIC

The following example instantiates the L10N service without any optional arguments. This will only enable the AddText and ExportToPOTFile methods.

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

The example below specifies the folder containing the PO files. Because the locale is not defined, the service instance will use the current LibreOffice locale settings.

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

The example above will result in an runtime error if the PO file for the current locale does not exist in the specified folder.

In the example below, both the folder name and locale settings are explicitly defined to be Belgian French.

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

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

## Eigenschappen

Naam | Alleen lezen | 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 als die is opgegeven.

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

##### In Python

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

## ExportToPOTFile

Exports a set of untranslated strings as a POT file.

To build a set of strings you can use either a succession of AddText method calls, or by a successful invocation of the L10N service with the foldername argument present. It is also possible to use a combination of both techniques.

The method returns True if successful.

### Syntaxis:

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

### Parameters:

filename: The output file in FileSystem.FileNaming notation.

header: Comments that will be added on top of the generated POT file.

Do not include any leading "#" characters. If you want the header to be broken into multiple lines, insert escape sequences (\n) where relevant. A standard header will be added alongside the text specified in the header argument.

encoding: The character set to be used (Default = "UTF-8").

### Voorbeeld:

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

The generated file should successfully pass the msgfmt --check GNU command.

## GetText

Gets the translated string corresponding to the given msgid argument.

A list of arguments may be specified to replace the placeholders (%1, %2, ...) in the string.

If no translated string is found, the method returns the untranslated string after replacing the placeholders with the specified arguments.

### Syntaxis:

This method can be called either by the full name GetText or by the shortcut _ (a single underscore):

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

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

In the ScriptForge library, all methods starting with the "_" character are reserved for internal use only. However, the shortcut _ used for GetText is the only exception to this rule, hence it can be safely used in Basic and Python scripts.

### Parameters:

msgid: The untranslated string, which is the text appearing in the program code. It must not be empty. It may contain any number of placeholders (%1 %2 %3 ...) that can be used to dynamically insert text at runtime.

Besides using a single msgid string, this method also accepts the following formats:

- The context string with which the method will retrieve the msgid in the PO file, or;

- A combination context|msgid, instructing the method to retrieve the msgid using specified context value. The second part of the argument is used to improve code readability.

args: Values to be inserted into the placeholders. Any variable type is allowed, however only strings, numbers and dates will be considered.

### Voorbeeld:

##### In BASIC

Consider the following code is running on a LibreOffice installation with locale set to "es-ES". Additionally, there is a file "es-ES.po" inside the specified folder that translates the string passed to the GetText method:

          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.

Verwante onderwerpen

ScriptForge.FileSystem service

Vertaling van besturingselementen in de dialoogeditor