Obsah
Rejstřík 🔎︎

# 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 tři následující metody:

- AddText: Použita programátorem k sestavení sady řetězců, které budou později přeloženy.

- 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ři vytvoření instance služby L10N je možné uvést dva nepovinné argumenty určující složku, kde jsou umístěny soubory PO, a národní prostředí, které se má použít.

### Syntaxe:

            CreateScriptService("L10N" [, FolderName As String [, Locale as String]])

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“).

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ář.

Tato služba je plně podporována v jazycích Basic i Python. Všechny příklady jsou uvedeny v programovacím jazyce Basic a lze je snadno převést na Python.

### Příklad:

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.

            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 aktuální nastavení národního prostředí v LibreOffice.

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

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.

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

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

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

## AddText

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

### Syntaxe:

           myPO.AddText(Context As String, MsgId As String, [Comment As String]) As Boolean

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

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

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

### Syntaxe:

             myPO.ExportToPOTFile(FileName As String, [Header As String], [Encoding As String])

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

             myPO.ExportToPOTFile("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.

### Syntaxe:

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

            myPO.GetText(MsgId As String[, Arg1[, Arg2[, ...]]]) As String
            myPO._(MsgId As String[, Arg1[, Arg2[, ...]]]) As String

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:

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

Arg1, ...: 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:

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:\MyPOFolder\")
          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.

Související témata

Služba ScriptForge.FileSystem

Překlad ovládacích prvků v editoru dialogových oken