Storitev ScriptForge.L10N

Ta storitev zagotavlja številne metode, ki se nanašajo na prevod nizov z minimalnim vplivom na izvorno kodo programa. Metode, ki jih zagotavlja storitev L10N, lahko predvsem uporabite za:

• ustvarjanje datotek POT, ki jih je mogoče uporabiti kot predloge za prevod vseh nizov v programu;

• pridobivanje prevedenih nizov v času izvajanja za jezik, definiran z lastnostjo Locale.

Okrajšava L10N predstavlja lokalizacijo (za angleško besedo localization) in se nanaša na nabor postopkov za prevajanje programja za uporabo v določeni državi ali regiji.

Datoteke PO so že dolgo časa v skupnosti prostega programja veljajo za sredstvo, ki zagotavlja večjezičnost uporabniških vmesnikov. To dosegajo zaradi za uporabnike enostavno berljivih besedilnih datotek z dobro določeno strukturo, ki za poljuben jezik določa niz v izvornem jeziku ter prevedeni oz. lokalizirani niz.

Osrednja prednost zapisa PO je neodvisnost programerja in prevajalca. Datoteke PO so neodvisne besedilne datoteke, da lahko programerji pošljejo datoteke predlog POT prevajalcem, ki lahko nato prevedejo njihovo vsebino in vrnejo prevedene datoteke PO za vsak podprti jezik posebej.

Storitev L10N sloni na implementaciji GNU za datoteke PO (angl. portable object). Če želite bolje spoznati ta zapis datotek, obiščite GNU GetText Utilities: PO Files (v angl.).

Ta storitev implementira naslednje metode:

• AddText: namenjeno programerju, da tvori nabor nizov, ki bodo prevedeni kasneje.

• AddTextsFromDialog: izlušči vse nize iz instance storitve Dialog.

• ExportToPOTFile: izvozi nize, ki jih metoda AddText doda v datoteko POT.

• GetText: pridobi prevedene nize v času izvajanja.

Upoštevajte, da se prvi metodi uporabljata za izdelavo nabora prevedljivih nizov in njihovega izvoza v datoteko POT. Ni pa nujno, da datoteke POT ustvarite s temi metodami. Ker gre za besedilne datoteke, jih lahko programer ustvari z vsakim urejevalnikom besedila.

Priklic storitve

Pred uporabo storitve L10N je potrebno naložiti ali uvoziti knjižnico ScriptForge:

• Za makre Basic mora biti naložena knjižnica ScriptForge z naslednjim ukazom:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Za skripte Python mora biti opravljen uvoz iz modula scriptforge:
from scriptforge import CreateScriptService

Priklic storitve L10N lahko izvedemo na več načinov z uporabo največ petih neobveznih argumentov, ki določajo mapo, kjer so shranjene datoteke PO, krajevne nastavitve in kodiranje, ki bodo uporabljeni, kot tudi nadomestno datoteko PO in njeno kodiranje.

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

foldername: mapa, ki vsebuje datoteke PO. Izražena mora biti v zapisu FileSystem.FileNaming.

locale: niz v obliki »je-DR« (jezik-DRŽAVA) ali zgolj v obliki »je« (jezik).

encoding: nabor znakov, ki naj bo uporabljen. Privzeto kodiranje je »UTF-8«.

locale2: niz, ki določa nadomestno krajevno nastavitev, ki naj se uporabi, če datoteka PO, ki ustreza krajevnim nastavitvam, določenim s parametrom locale, ne obstaja. Ta parameter je izražen v obliki »je-DR« (jezik-DRŽAVA za angl. »je-DR« oz. language-COUNTRY) ali le »je« (jezik za angl. language).

encoding2: nabor znakov nadomestne datoteke PO, ki ustreza argumentu locale2. Privzeto kodiranje je »UTF-8«.

Če želite izvedeti več o imenih naborov znakov, si oglejte stran Nabori znakov IANA (IANA's Character Set) (v angl.). Upoštevajte, da LibreOffice ne podpira vseh obstoječih naborov znakov.

Naslednji primer prikliče storitev L10N brez neobveznih argumentov. To bo omogočilo le metodi AddText in ExportToPOTFile, kar je uporabno za ustvarjanje datotek POT.

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

V spodnjem primeru je določena mapa, ki vsebuje datoteke PO. Ker krajevna nastavitev ni določena, bo instanca storitve uporabila trenutno krajevno nastavitev uporabniškega vmesnika LibreOffice, ki je ista krajevna nastavitev, kot je določena z lastnostjo OfficeLocale storitve Platform.

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

Zgornji primer povzroči napako ob izvajanju, če datoteka PO za trenutno izbrano krajevno nastavitev OfficeLocale v navedeni mapi ne obstaja.

V spodnjem primeru je krajevna nastavitev izrecno določena za belgijsko francoščino (»fr-BE«), zato bo storitev naložila datoteko »fr-BE.po« iz mape »C:\myPOFiles«. Če datoteka ne obstaja, bo prišlo do napake.

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

Da bi se izognili napakam, lahko določite želeno in nadomestno krajevno nastavitev in kodiranje. Naslednji primer najprej poskusi naložiti datoteko »fr-BE.po« iz navedene mape, če ta ne obstaja, naloži datoteko »en-US.po«.

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

Datoteke PO morajo biti poimenovane v obliki "je-DR.po" ali "je.po", kjer "je" predstavlja jezik, "DR" pa državo. Nekaj primerov: "en-US.po", "fr-BE.po" ali "sl.po".

Priporočamo, da po uporabi sprostite vire:

      Set myPO = myPO.Dispose()
    

Zgornje primere lahko prevedemo v Python na sledeč način:

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

Sobiva lahko več instanc storitve L10N. Vendar mora vsaka instanca uporabljati ločeno mapo za svoje datoteke PO.

Lastnosti

AddText

Doda nov vnos na seznam nizov za prevajanje. Ne sme še obstajati.

Ta metoda vrne True, če uspe.

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

context: ključ za pridobivanje prevedenega niza z metodo GetText. Ta parameter ima privzeto vrednost "".

msgid: neprevedeni niz, torej besedilo, ki se pojavlja v programski kodi. Ne sme biti prazen. msgid postane ključ za pridobivanje prevedenega niza prek metode GetText, če je context prazen.

Niz msgid lahko vsebuje poljubno število ograd (%1 %2 %3 ...), s katerimi lahko dinamično spreminjate niz med izvajanjem programa.

comment: neobvezen komentar, ki ga lahko dodate k nizu kot pomoč prevajalcem.

Spodnji primer ustvari množico nizov v angleškem jeziku:

      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

Samodejno izlušči nize iz pogovornega okna in jih doda na seznam besedilnih nizov, ki jih je mogoče prevesti. Izluščijo se naslednji nizi:

• Naziv pogovornega okna.

• Napisi iz naslednjih vrst kontrolnikov: gumb (Buttin), potrditveno polje (CheckBox), fiksna vrstica (FixedLine), skupinsko polje (GroupBox) in izbirni gumb (RadioButtin).

• Nespremenljivi nizi v seznamskih poljih in kombiniranih poljih.

• Namig oz. besedilo pomoči, ki se prikazuje, če se z miško ustavite nad kontrolnikom.

Ta metoda vrne True, če uspe.

Pogovorno okno, iz katerega bodo izluščeni nizi, ob klicu metode ne sme biti odprto.

Ko je ustvarjena instanca storitve L10N iz obstoječe datoteke PO, uporabite metodo GetTextsFromL10N iz storitve Dialog, da samodejno naložite vse prevedene nize v pogovorno okno.

svc.AddTextsFromDialog(dialog: svc): bool

dialog: instanca storitve Dialog, ki ustreza pogovornemu oknu, iz katerega bodo izluščeni nizi.

Naslednji primer izlušči vse nize iz pogovornega okna »MyDialog«, shranjenega v knjižnici »Standard«, in jih izvozi v datoteko 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

Izvozi množico neprevedenih nizov v datoteko POT.

Za gradnjo množice nizov lahko uporabite niz klicev metode AddText ali uspešen klic storitve L10N s prisotnim argumentom foldername. Uporabite lahko tudi kombinacijo obeh tehnik.

Ta metoda vrne True, če uspe.

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

filename: polno ime izhodne datoteke v notaciji FileSystem.FileNaming.

header: komentarji, ki bodo dodani na vrh izdelane datoteke POT.

Ne vključite "#" kot vodilnih znakov. Če želite, da je glava razbita na več vrstic, vstavite ubežni znak (\n), kjer je potrebno. Standardna glava bo dodana ob v argumentu header navedenem besedilu.

encoding: uporabljeni nabor znakov (privzeta vrednost je "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')
    

Izdelana datoteka bi morala uspešno prestati preizkus z ukazom GNU msgfmt --check.

GetText

Pridobi prevod niza glede na podani argument msgid.

Določen ima lahko seznam argumentov, ki v nizu nadomestijo ograde (%1, %2, ...).

Če ne najde prevedenega niza, metoda vrne neprevedeni niz, potem ko zamenja ograde z vrednostmi navedenih argumentov.

To metodo lahko pokličete po polnem imenu GetText ali z okrajšavo _ (en sam podčrtaj):

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

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

V knjižnici ScriptForge so vse metode, ki se začenjajo z znakom "_", rezervirane zgolj za interno uporabo. Okrajšava _, ki se uporablja za GetText, je edina izjema tega pravila, zato jo lahko varno uporabljate v skriptih Basic in Python.

msgid: neprevedeni niz, torej besedilo, ki se pojavlja v programski kodi. Ne sme biti prazen. Vsebuje lahko poljubno število ograd (%1 %2 %3 ...), s katerimi lahko dinamično vstavljate besedilo med izvajanjem programa.

Poleg uporabe posameznega niza msgid ta metoda sprejema tudi naslednje oblike:

• niz context, s katerim metoda pridobi msgid iz datoteke PO;

• kombinacijo context|msgid, ki usmeri metodo, da pridobi msgid z uporabo določene vrednosti context. Drugi del argumenta je namenjen boljši berljivosti kode.

arg1, arg2, ...: vrednosti, ki bodo vstavljene v ograde. Dovoljene so vse vrste spremenljivk, vendar so obravnavani le nizi, številke in datumi.

Upoštevajte, da se naslednja koda izvaja na namestitvi LibreOffice s krajevno nastavitvijo "es-ES". Poleg tega je datoteka "es-ES.po" v navedeni mapi, ki prevede podani niz, podanega metodi 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"
    

Vsi podprogrami ali identifikatorji ScriptForge Basic s predpono podčrtaja (»_«) so rezervirani za interno uporabo. Uporabi v makrih Basic ali skriptih Python niso namenjeni.