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

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.

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

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

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.

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

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.

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

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

      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ů:

• Nadpis dialogového okna.

• Popisky následujících druhů ovládacích prvků: Button, CheckBox, FixedLine, FixedText, GroupBox a RadioButton.

• Statické řetězce v prvcích ListBox a ComboBox.

• Tip nebo text nápovědy zobrazený při najetí myší nad ovládací prvek.

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

Dialogové okno, z něhož se mají řetězce získat, nesmí být při volání metody otevřeno.

Jestliže je instance služby L10N vytvořena z existujícího souboru PO, všechny přeložené řetězce načtete do dialogového okna metodou GetTextsFromL10N ze služby Dialog.

svc.AddTextsFromDialog(dialog: svc): bool

dialog: Instance služby Dialog odpovídající dialogového okno, z nějž se řetězce získají.

V následujícím příkladu se získají všechny řetězce z dialogového okna "MyDialog" uloženého v knihovně "Standard" a vyexportují se do souboru POT:

      oDlg = CreateScriptService("Dialog", "GlobalScope", "Standard", "MyDialog")
      myPO = CreateScriptService("L10N")
      myPO.AddTextsFromDialog(oDlg)
      myPO.ExportToPOTFile("C:\en-US.pot")
    

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

ExportToPOTFile

Vyexportuje sadu nepřeložených řetězců jako soubor POT.

Sadu řetězců můžete vytvořit buď postupným opakovaným voláním metody AddText, nebo vytvořením instance služby L10N se zadaným argumentem foldername. Lze také použít kombinaci obou možností.

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

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

filename: Úplný název výstupního souboru v zápisu FileSystem.FileNaming.

header: Komentář, který se přidá na začátek vygenerovaného souboru POT.

Nepřidávejte uvozující znaky "#". Chcete-li záhlaví rozdělit na více řádků, vložte na příslušná místa escape sekvence (\n). Kromě textu zadaného v argumentu header bude do souboru přidáno standardní záhlaví.

encoding: Znaková sada, která se má použít (výchozí = "UTF-8").

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

Vygenerovaný soubor by měl úspěšně projít kontrolou příkazem GNU msgfmt --check.

GetText

Získá přeložené řetězce odpovídající zadanému argumentu msgid.

Lze zadat také seznam argumentů, kterými se nahradí zástupné znaky (%1, %2, ...) v řetězci.

Není-li nalezen žádný přeložený řetězec, metoda vrátí nepřeložený řetězec se zástupnými znaky nahrazenými zadanými argumenty.

Metodu je možné zavolat úplným názvem GetText nebo zkratkou _ (jedno podtržítko):

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

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

V knihovně ScriptForge jsou všechny metody začínající znakem "_" vyhrazeny pouze pro interní použití. Jedinou výjimkou z tohoto pravidla je právě zkratka _ znamenající metodu GetText, lze ji tedy ve skriptech Basicu a Pythonu bez obav používat.

msgid: Nepřeložený řetězec, tj. text zobrazující se v kódu programu. Nesmí být prázdný. Může obsahovat libovolný počet zástupných znaků (%1 %2 %3...), které lze použít pro dynamické vkládání textu za běhu programu.

Kromě použití jediného řetězce msgid je možné metodě předat také následující formáty:

• Řetězec context, s nímž metoda získá msgid ze souboru PO.

• Kombinaci context|msgid, značící, že metoda má získat msgid za použití zadané hodnoty context. Druhá část argumentu se používá v zájmu zlepšení čitelnosti kódu.

args: Hodnoty, které se mají vložit na místa zástupných znaků. Povolena je jakákoliv proměnná, použijí se však pouze řetězce, čísla a data.

Následující kód je spuštěn na nainstalovaném LibreOffice s národním prostředím nastaveným na "cs-CZ". V uvedené složce se navíc nachází soubor "cs-CZ.po" s překlady řetězců předávaných metodě GetText:

      myPO = CreateScriptService("L10N", "C:\myPOFiles\")
      myPO.GetText("Welcome %1! Hope you enjoy this program", "John")
      ' "¡Bienvenido John! Espero que disfrutes de este programa"
    

      myPO = CreateScriptService('L10N', r"C:\myPOFiles")
      myPO.GetText('Welcome %1! Hope you enjoy this program', 'John')
      # "¡Bienvenido John! Espero que disfrutes de este programa"
    

Všechny procedury nebo identifikátory knihovny ScriptForge, které jsou uvozeny podtržítkem "_", jsou určeny pro interní použití. Není zamýšleno je používat v makrech Basicu nebo skriptech Pythonu.