ScriptForge.L10N szolgáltatás

Tartalom
Index 🔎︎

# ScriptForge.L10N service

This service provides a number of methods related to the translation of strings with minimal impact on the program's source code. The methods provided by the L10N service can be used mainly to:

- Create POT files that can be used as templates for translation of all strings in the program.

- Get translated strings at runtime for the language defined in the Locale property.

The acronym L10N stands for Localization and refers to a set of procedures for translating software to a specific country or region.

A PO fájlokat a szabad szoftverek közösségében már régóta népszerűsítik, mint a többnyelvű felhasználói felületek biztosításának eszközét. Ezt az ember által olvasható szövegfájlok használatával érik el, amelyek jól meghatározott struktúrával rendelkeznek, amely bármely adott nyelv esetében meghatározza a forrásnyelvi és a lokalizált karakterláncot.

A PO formátum fő előnye a programozó és a fordító szétválasztása. A PO fájlok független szövegfájlok, így a programozó elküldheti a POT sablonfájlokat a fordítóknak, akik lefordítják a tartalmukat, és visszaküldik a lefordított PO fájlokat minden támogatott nyelvre.

The L10N service is based on the GNU implementation of PO (portable object) files. To learn more about this file format, visit GNU gettext Utilities: PO Files.

This service implements the methods listed below:

- AddText: Used by the programmer to build a set of strings that will be translated later.

- AddTextsFromDialog: Extracts all strings from a Dialog service instance.

- ExportToPOTFile: Exports the strings added by the AddText method to a POT file.

- GetText: Gets the translated strings at runtime.

Vegyük észre, hogy az első két módszer a fordítható karakterláncok készletének létrehozására és POT fájlba való exportálására szolgál. POT-fájlokat azonban nem csak ezekkel a módszerekkel lehet létrehozni. Mivel ezek szövegfájlok, a programozó bármilyen szövegszerkesztővel létrehozhatta volna őket.

## A szolgáltatás igénybevétele

Before using the L10N service the ScriptForge library needs to be loaded or imported:

• Basic macros require to load ScriptForge library using the following statement:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Python scripts require an import from scriptforge module:
from scriptforge import CreateScriptService

A L10N szolgáltatás többféleképpen is meghívható, legfeljebb öt opcionális argumentummal, amelyek megadják a PO-fájlok tárolási mappáját, a használandó nyelvi konfigurációt és kódolást, valamint egy tartalék PO-fájlt és annak kódolását.

### Szintaxis:

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

foldername: The folder containing the PO files. It must be expressed in the FileSystem.FileNaming notation.

locale: A string in the form "la-CO" (language-COUNTRY) or in the form "la" (language) only.

encoding: The character set to be used. The default encoding is "UTF-8".

locale2: Ha a locale paraméterben meghatározott nyelvnek megfelelő PO fájl nem létezik, ez a nyelvi konfiguráció kerül használatra. Ez a paraméter csak a "la-CO" (language-COUNTRY) vagy a "la" (language) formában fejezhető ki.

encoding2: The character set of the fallback PO file corresponding to the locale2 argument. The default encoding is "UTF-8".

To learn more about the names of character sets, visit IANA's Character Set page. Be aware that LibreOfficeDev does not implement all existing character sets.

### Példa:

##### In Basic

The following example instantiates the L10N service without any optional arguments. This will only enable the AddText and ExportToPOTFile methods, which is useful for creating POT files.

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

Az alábbi példa a PO-fájlokat tartalmazó mappát adja meg. Mivel a nyelvi konfiguráció nem került meghatározásra, a szolgáltatáspéldány a LibreOfficeDev felhasználói felülethez definiált nyelvi konfigurációt fogja használni, amely megegyezik a Platform szolgáltatás OfficeLocale tulajdonságában meghatározott nyelvi konfigurációval.

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

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

Az alábbi példában a nyelvterület kifejezetten belga francia ("fr-BE"), ezért a szolgáltatás a "fr-BE.po" fájlt tölti be a "C:\myPOFiles" mappából. Ha a fájl nem létezik, hibaüzenet jelenik meg.

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

A hibák elkerülése érdekében lehetőség van egy preferált és egy tartalék területi beállítás és kódolás megadására. A következő példa először a "fr-BE.po" fájlt próbálja betölteni a megadott mappából, és ha nem létezik, akkor az "en-US.po" fájlt tölti be.

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

PO files must be named in the form "la-CO.po" or "la.po", where "la" refers to the language and "CO" is the country. Some examples are: "en-US.po", "fr-BE.po" or "fr.po".

It is recommended to free resources after use:

          Set myPO = myPO.Dispose()

##### In Python

The examples above can be translated to Python as follows:

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

Several instances of the L10N service may coexist. However, each instance must use a separate directory for its PO files.

## Tulajdonságok

Név | Írásvédett | Típus | Leírás
--- | --- | --- | ---
Folder | Igen | String | The folder containing the PO files (see the FileSystem.FileNaming property to learn about the notation used).
Languages | Igen | Array | A zero-based array listing all the base names (without the ".po" extension) of the PO-files found in the specified Folder.
Locale | Igen | String | The currently active language-COUNTRY combination. This property will be initially empty if the service was instantiated without any of the optional arguments.

List of Methods in the L10N Service
AddText AddTextsFromDialog | ExportToPOTFile | GetText

## AddText

Adds a new entry in the list of localizable strings. It must not exist yet.

The method returns True if successful.

### Szintaxis:

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

### Paraméterek:

context: The key to retrieve the translated string with the GetText method. This parameter has a default value of "".

msgid: A lefordítatlan karakterlánc, amely a programkódban megjelenő szöveg. Nem lehet üres. A msgid lesz a kulcs a lefordított karakterlánc GetText módszerrel történő lekérdezéséhez, ha a context üres.

The msgid string may contain any number of placeholders (%1 %2 %3 ...) for dynamically modifying the string at runtime.

comment: Optional comment to be added alongside the string to help translators.

### Példa:

The example below creates a set of strings in English:

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

Automatically extracts strings from a dialog and adds them to the list of localizable text strings. The following strings are extracted:

- The title of the dialog.

- The caption of the following control types: Button, CheckBox, FixedLine, FixedText, GroupBox and RadioButton.

- Static strings in ListBoxes and ComboBoxes.

- The tooltip or help text displayed when the mouse hovers over the control.

The method returns True if successful.

The dialog from which strings will be extracted must not be open when the method is called.

When a L10N service instance is created from an existing PO file, use the GetTextsFromL10N method from the Dialog service to automatically load all translated strings into the dialog.

### Szintaxis:

svc.AddTextsFromDialog(dialog: svc): bool

### Paraméterek:

dialog: a Dialog service instance corresponding to the dialog from which strings will be extracted.

### Példa:

The following example extracts all strings from the dialog "MyDialog" stored in the "Standard" library and exports them to a POT file:

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

A karakterláncok készletének létrehozásához vagy a AddText metódushívások sorozatát használhatjuk, vagy a L10N szolgáltatás sikeres meghívását a foldername argumentum jelenlétében. Lehetséges a két technika kombinációja is.

The method returns True if successful.

### Szintaxis:

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

### Paraméterek:

filename: The output file in FileSystem.FileNaming notation.

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

Ne tartalmazzon "#" karaktereket első karakterként. Ha azt szeretné, hogy az élőfej több sorra legyen bontva, illesszen be escape sorozatokat (\n), ahol szükséges. A header argumentumban megadott szöveghez egy szabványos élőfej kerül.

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

### Példa:

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

### Szintaxis:

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

A ScriptForge programkönyvtárban minden "_" karakterrel kezdődő metódus csak belső használatra van fenntartva. A _ rövidítés, amelyet a GetText esetében használunk, azonban az egyetlen kivétel ez alól a szabály alól, ezért nyugodtan használható Basic és Python parancsfájlokban.

### Paraméterek:

msgid: A lefordítatlan karakterlánc, amely a programkódban megjelenő szöveg. Nem lehet üres. Bármennyi helykitöltőt tartalmazhat (%1 %2 %3 ...), amelyekkel futás közben dinamikusan beilleszthető a szöveg.

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.

### Példa:

##### In Basic

Tekintsük, hogy a következő kód egy LibreOfficeDev telepítésen fut, ahol a nyelvi beállítás "es-ES". Ezenkívül van egy "es-ES.po" fájl a megadott mappában, amely lefordítja a GetText metódusnak átadott karakterláncot:

          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"

All ScriptForge Basic routines or identifiers that are prefixed with an underscore character "_" are reserved for internal use. They are not meant be used in Basic macros or Python scripts.

Kapcsolódó témakörök

ScriptForge.FileSystem service

Vezérlőelemek fordítása a párbeszédablak-szerkesztő segítségével