Služba ScriptForge.L10N

Tato služba nabízí řadu metod souvisejících s překladem řetězců s minimálním zásahem do zdrojového kódu programu. Metody poskytované službou L10 lze použít zejména pro:

Vytvoření souborů POT, které je možné použít jako šablony pro překlad všech řetězců programu.
Získání přeložených řetězců za běhu programu, a to pro jazyk stanovený ve vlastnosti Locale.

Zkratka L10N značí lokalizaci („localization“), tj. sadu postupů pro přizpůsobení softwaru určité zemi či regionu.

Ve světě svobodného softwaru jsou pro tvorbu vícejazyčných uživatelských rozhraní dlouhodobě používány soubory PO. Jedná se o lidsky čitelné textové soubory s dobře definovanou strukturou, které pro libovolný jazyk udávají řetězec zdrojového jazyka a jemu odpovídající lokalizovaný řetězec.

Hlavní výhodou formátu PO je oddělení práce programátora a překladatele. Soubory PO jsou nezávislé textové soubory, programátor tak může šablonu POT poslat překladatelům, kteří její obsah přeloží a vrátí zpět přeložené soubory PO pro všechny podporované jazyky.

Služba L10N využívá implementaci souborů PO („portable object“) od projektu GNU. Další informace o tomto formátu souboru naleznete na stránce GNU gettext Utilities: PO Files.

Služba implementuje následující metody:

AddText: Použita programátorem k sestavení sady řetězců, které budou později přeloženy.
AddTextsFromDialog: Získá všechny řetězce z instance služby Dialog.
ExportToPOTFile: Vyexportuje řetězce přidané metodou AddText do souboru POT.
GetText:Získá přeložené řetězce za běhu programu.

První dvě metody se používají pro vytvoření řetězců k překladu a jejich exportu do souboru POT. Není však povinné vytvářet soubory POT tímto způsobem. Jelikož se jedná o textové soubory, může je programátor připravit v libovolném textovém editoru.

Volání služby

Před používáním služby L10N je nutné načíst či naimportovat knihovnu ScriptForge pomocí:

• V makrech Basicu je nutné načíst knihovnu ScriptForge následujícím příkazem:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Ve skriptech Pythonu je nezbytné import z modulu scriptforge:
from scriptforge import CreateScriptService

Instanci služby L10N je možné vytvořit několika způsoby za pomoci až pěti nepovinných argumentů, které určují složku, kde jsou umístěny soubory PO, národní prostředí a kódování, které se mají použít, a záložní soubor PO a jeho kódování.

Syntaxe:

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

foldername: Název složky obsahující soubory PO. Musí odpovídat zápisu FileSystem.FileNaming.

locale: Řetězec ve tvaru "la-CO" („language-COUNTRY“, jazyk a země) nebo pouze ve tvaru "la" („language“).

encoding: Znaková sada, která se má použít. Výchozím kódováním je "UTF-8".

locale2: Řetězec určující záložní národní prostředí, které se použije v případě, že neexistuje soubor PO odpovídající národnímu prostředí z parametru locale. Je vyjádřen ve formátu "la-CO" (language-COUNTRY, jazyk a země) nebo pouze "la" (language, jazyk).

encoding2: Znaková sada záložního souboru PO odpovídající argumentu locale2. Výchozí znakovou sadou je "UTF-8".

Podrobnosti o názvech znakových sad naleznete na stránce znakových sad IANA. Mějte na paměti, že v LibreOffice nemusí být všechny znakové sady implementovány.

Příklad:

V Basicu

V následujícím příkladu se vytvoří instance služby L10N bez nepovinných parametrů. To umožní používat pouze metody AddText a ExportToPOTFile, které se využívají při vytváření souborů POT.


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

Níže uvedený příklad určuje složky obsahující soubory PO. Protože není určeno národní prostředí, instance služby použije národní prostředí nastavené pro uživatelské rozhraní LibreOffice, které se shoduje s národním prostředím definovaným vlastností OfficeLocale služby Platform.


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

Výše uvedený příklad skončí běhovou chybou, pokud soubor PO odpovídající národnímu prostředí OfficeLocale v zadané složce neexistuje.

V následujícím příkladu je explicitně uveden jak název složky, tak národní prostředí, kterým je francouzština pro Belgii ("fr-BE"). Služba tak načte soubor "fr-BE.po" ze složky "C:\myPOFiles". Pokud takový soubor neexistuje, nastane chyba.


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

Chcete-li se chybám vyhnout, můžete stanovit upřednostňované a záložní národní prostředí a kódování. V následujícím příkladu se nejprve načte ze zadané složky soubor "fr-BE.po", a jestliže tento soubor neexistuje, načte se soubor "en-US.po".


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

Soubory PO je nutné pojmenovat ve tvaru "la-CO.po" nebo "la.po", kde "la" značí jazyk („language“) a "CO" zemi („country“). Příklady mohou být: "en-US.po", "fr-BE.po", "fr.po" nebo "cs-CZ.po".

Po použití se doporučuje uvolnit zdroje:


      Set myPO = myPO.Dispose()

V Pythonu

Do Pythonu lze tyto příklady převést následovně:


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

Současně může existovat více instancí služby L10N. Každá z nich ovšem musí používat pro své soubory PO oddělený adresář.

Vlastnosti

Název	Pouze pro čtení	Typ	Popis
Folder	ano	String	Složka obsahující soubory PO (použitý zápis musí odpovídat vlastnosti FileSystem.FileNaming).
Languages	ano	Array	Pole začínající od 0 se seznamem všech názvů souborů PO (bez přípony ".po") nacházejících se v zadané složce Folder.
Locale	ano	String	Aktuálně aktivní kombinace jazyk-ZEMĚ. Tato vlastnost bude na začátku prázdná, pokud byla instance služby vytvořena bez nepovinných argumentů.

Seznam metod služby L10N
AddText AddTextsFromDialog	ExportToPOTFile	GetText

AddText

Přidá do seznamu lokalizovatelných řetězců novou položku, která dosud nesmí existovat.

V případě úspěšného přidání vrátí metoda True.

Syntaxe:

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

Parametry:

context: Klíč, pomocí kterého se získá přeložený řetězec metodou GetText. Tento parametr má výchozí hodnotu "".

msgid: Nepřeložený řetězec, tj. text zobrazující se v kódu programu. Nesmí být prázdný. Argument msgid bude použit jako klíč pro získání přeloženého řetězce metodou GetText v případě, že je argument context prázdný.

Řetězec msgid může obsahovat libovolný počet zástupných znaků (%1 %2 %3...), které umožní měnit řetězec dynamicky za běhu programu.

comment: Nepovinný komentář, který se má přidat k řetězci jako pomocná informace pro překladatele.

Příklad:

V následujícím příkladu je vytvořena sada řetězců v angličtině:

V Basicu


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

V Pythonu


      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

Automaticky získá řetězce z dialogového okna a přidá je do seznamu lokalizovatelných řetězců. Týká se to následujících řetězců: