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:

note

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.

tip

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:

note

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

note

• 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".

note

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

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

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

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

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

note

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.

Syntaxe:

svc.AddTextsFromDialog(dialog: svc): bool

Parametry:

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

Příklad:

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:

V Basicu

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

      dlg = CreateScriptService("Dialog", "GlobalScope", "Standard", "Dialog1")
      myPO = CreateScriptService("L10N")
      myPO.AddTextsFromDialog(dlg)
      myPO.ExportToPOTFile("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.

Syntaxe:

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

Parametry:

filename: Výstupní soubor 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").

Příklad:


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

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.

Syntaxe:

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

note

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.


Parametry:

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:

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.

Příklad:

V Basicu

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"
    
V Pythonu

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

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.


Podpořte nás!