Słužba ScriptForge.L10N

Tuta słužba rjad metodow nastupajo přełožowanje znamješkowych rjećazkow z minimalnym wuskutkowanjom na žórłowy kod programa skići. Metody, kotrež słužba L10N skići, dadźa so hłownje wužiwać, zo bychu:

Dataje POT wuwtorili, kotrež dadźa so jako dokumentowe přikłady za přełožowanje wšěch znamješkowych rjećazkach w programje wužiwać.
we wuwjedźenskim času přełožene znamješkowe rjećazki dóstali, kotrež su w kajkosći Locale definowane.

Akronym L10N so na jendźelske słowo Localization (lokalizacija) steji a poćahuje so na rjad procedurow za přełožowanje software za wěsty kraj abo region.

PO-dataje so hižo dawno w swobodnym softwarowym zhromadźenstwje jako srědk za poskićenje wjacerěčnych wužiwarskich powjerchow spěchuja. To so přez wot ludźi čitajomnych tekstowych datajow docpěwa, z derje definowanej strukturu, kotraž za datu rěč znamješkowy rjećazk žórłoweje rěče a lokalizowany znamješkowy rjećazk podawa.

Hłowna lěpšina PO-formata je wotdźělenje programowarja wot přełožowarja. PO-dataje su njewotwisne tekstowe dataje, zo by programowar dataje dokumentowych předłohow POT na přełožowarjow pósłać, kotřiž potom jich wobsah přełožuja a přełožene PO-dataje za kóždu podpěranu rěč wróćo sćelu.

Słužba L10N na implementaciji GNU PO-datajow (portable object) bazuje. Zo byšće wjace wo tutym datajowym formaće zhonił, wopytajće GNU gettext Utilities: PO Files (jendźelsce).

Tuta słužba deleka podate metody implementuje:

AddText: Wužiwa so wot programowarja, kotryž rkad znamješkowych rjećazkow wutworja, kotrež so pozdźišo přełožuja.
AddTextsFromDialog: Ekstrahuje wšě znamješkowe rjećazki ze słužboweje instancy Dialog.
ExportToPOTFile: Eksportuje znamješkowe rjećazki, kotrež su so POT-dataji přez metodu AddText přidali.
GetText: Wobstara přełožene znamješkowe rjećazki we wuwjedźenskim času.

Dźiwajće na to, zo so prěnjej dwě metodźe wužiwatej, zo byštej rjad přełožujomnych znamješkowych rjećazkow wutworiłoj a je do POT-dataje eksportowałoj. Ale trjeba njeje, POT-dataje z pomocu tuteju metodow wutworić. Dokelž su tekstowe dataje, móhł programowar je z někajkim tekstowym editorom wutworić.

Słužbowe wuwołanje

Před wužiwanjom słužby L10N dyrbi so biblioteka ScriptForge začitać abo importować:

• Makra Basic sej wužaduja, zo so biblioteka ScriptForge z pomocu slědowaceho přikaza začituje:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Skripty Python sej import z modula scriptforge wužaduja:
from scriptforge import CreateScriptService

Su wjacore móžnosće, zo by so słužba L10N z pomocu hač do pjeć opcionalnych argumentow wuwołała, kotrež rjadowak podawaja, hdźež su PO-dataje składowane, narodnu šemu a kodowanje, kotrež so ma wužiwać, kaž tež wuhibnu PO-dataju a jeje kodowanje.

Syntaksa:

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

foldername: Rjadowak, kotryž PO-dataje wobsahuje. Dyrbi so w notaciji FileSystem.FileNaming podać.

locale: Znamješkowy rjećazk we formje "la-CO" (language-COUNTRY, rěč-KRAJ) abo we formje "la" (rěč).

encoding: Znamješkowa sadźba, kotraž so ma wužiwać. Standardne kodowanje je „UTF-8“.

locale2: Znamješkowy rjećazk, kotryž wuhibnu narodnu šemu podawa, kotraž so ma wužiwać, jeli PO-Dataja, kotraž narodnej šemje wotpowěduje, kotraž je so w parametrje locale definowała, njeeksistuje. Tutón parameter so we formje "la-CO" (language-COUNTRY, rěč-KRAJ) abo "la" (rěč) podawa.

encoding2: Znamješkowa sadźba wuhibneje PO-dataje, kotraž argumentej locale2 wotpowěduje. Standardne kodowanje je „UTF-8“.

Zo byšće wjace wo mjenach znamješkowych sadźbow zhonił, wopytajće stronu Character Sets IANA. Dźiwajće na to, LibreOffice nic wšě eksistowace znamješkowe sadźby implementuje.

Přikład:

W Basic

Slědowacy přikład słužbu L10N bjez opcionalnych argumentow instancuje. To jenož metodźe AddText a ExportToPOTFile zmóžni, štož je za wutworjenje POT-datajow wužitne.


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

Slědowacy přikład rjadowak podawa, kotryž PO-dataje wobsahuje. Dokelž narodna šema definowana njeje, słužbowa instanca narodnu šemu wužiwa, kotraž je za wužiwarski powjerch LibreOffice definowana, kotraž je samsna narodna šema, kotraž je w kajkosći OfficeLocale słužby Platform definowana.


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

Přikład horjeka k wuwjedźenskočasowemu zmylkej wjedźe, jeli PO-dataja, kotraž narodnej šemje OfficeLocale wotpowěduje, w podatym rjadowaku njeeksistuje.

W slědowacym přikładźe je narodna šema eksplicitnje jako begliska francošćina ("fr-BE") definowana, dokelž słužba dataju „fr-BE.po“ z rjadowaka „C:\myPOFiles“ začita. Jeli dataja njeeksistuje, zmylk nastanje.


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

Zo byšće zmylki wobešoł, je móžno, preferowanu a wuhibnu narodnu šemu a kodowanje podać. Slědowacy přikład najprjedy pospytuje dataju „fr-BE.po“ z podateho rjadowaka začitać a jeli njeeksistuje, so dataja „en-US“ začita.


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

PO-dataje dyrbja so we formje „la-CO.po“ abo „la.po“ mjenować, při čimž „la“ so na rěč a „CO“ na kraj poćahuje. Někotre přikłady su: „en-US.po“, „fr-BE.po“ abo „fr.po“.

Poruča so, resursy po wužiwanju wuswobodźić:


      Set myPO = myPO.Dispose()

W Python

Přikłady horjeka dadźa so takle do Python přełožić:


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

Wjacore instancy słužby L10N móža koeksistować. Ale kóžda instanca dyrbi swójski zapis za swoje PO-dataje wužiwać.

Kajkosće

Mjeno	Přećiwo pisanju škitany	Typ	Wopisanje
Folder	Haj	String	Rjadowak, kotryž PO-dataje wobsahuje (hlejće kajkosć FileSyste.FileNaming, zo byšće wjace wo wužitej notaciji zhonił).
Languages	Haj	Array	Na nuli bazowaca matriks, kotraž wšě bazowe mjena (bjez kóncowki „.po“) PO-datajow nalistuje, kotrež su w Folder podate.
Locale	Haj	String	Tuchwilu aktiwna kombinacija rěč-KRAJ. Tuta kajkosć je spočatnje prózdna, jeli je so słužba bjez opcionalnych argumentow instancowała.

Lisćina metodow w słužbje L10N
AddText AddTextsFromDialog	ExportToPOTFile	GetText

AddText

Přidawa nowy zapisk w lisćinje lokalizujomnych znamješkowych rjećazkow. Njesmě hišće eksistować.

Metoda True wróći, jeli je wuspěšna.

Syntaksa:

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

Parametry:

context: Kluč za wotwołanje přełoženeho znamješkoweho rjećazka z metodu GetText. Tutón parameter ma standardnu hódnotu "".

msgid: Njepřełoženy znamješkowy rjećazk, kotryž je tekst, kotryž so w programowym kodźe jewi. Njesmě prózdny być. msgid budźe kluč za wotwołanje přełoženeho znamješkoweho rjećazka přez metodu GetText, hdyž context je prózdny.

Znamješkowy rjećazk msgid móže rjad wariablow (%1 %2 %2 …) wobsahować, zo by znamješkowy rjećazk we wuwjedźenskim času dynamisce změnił.

comment: Opcionalny komentar, kotryž so hromadźe ze znamješkowym rjećazkom přidawa, zo by přełožowarjam pomhał.

Přikład:

Slědowacy přikład rjad znamješkowych rjećazkow w jendźelšćinje wutwori:

W Basic


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

W Python


      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

Ekstrahuje awtomatisce znamješkowe rjećazki z dialoga a přidawa je lisćinje lokalizujomnych tekstowych znamješkowych rjećazkow. Slědowace znamješkowe rjećazki so ekstrahuja:

Titul dialoga.
Popis slědowacych typow wodźenskich elementow: tłóčatko, kontrolny kašćik, škitana linija, njezměnite tekstowe polo a opciske tłóčatko.
Statiske znamješkowe rjećazki w lisćinowych a kombinaciskich polach.
Pomocny tekst, kotryž so pokazuje, hdyž so myška nad wodźenski element pohibuje.

Metoda True wróći, jeli je wuspěšna.

Dialog, z kotrehož so maja znamješkowe rjećazki ekstrahować, njesmě wočinjeny być, hdyž so metoda wuwołuje.

Hdyž so słužbowa instanca L10N z eksistowaceje PO-dataje wutworja, wužiwajće metodu GetTextsFromL10N ze słužby Dialog, zo byšće wšě přełožene znamješkowe rjećazki awtomatisce do dialoga začitał.

Syntaksa:

svc.AddTextsFromDialog(dialog: svc): bool

Parametry:

dialog: Słužbowa instanca Dialog, kotraž dialogej wotpowěduje, z kotrehož so znamješkowe rjećazki ekstrahuja.

Přikład:

Slědowacy přikład wšě znamješkowe rjećazki z dialog "MyDialog" ekstrahuje, kotrež su w bibliotece "Standard" składowane a eksportuje je do POT-dataje:

W Basic


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

W Python


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

ExportToPOTFile

Eksportuje sadźbu njepřełoženych znamješkowych rjećazkow jako POT-dataja.

Zo byšće sadźbu znamješkowych rjećazkow wutworił, móžeće pak rjad wuwołanjow metody AddText pak wuspěšne wuwołanje słužby L10N z eksistowacym argumentom foldername. Je tež móžno, kombinaciju wobeju technikow wužiwać.

Metoda True wróći, jeli je wuspěšna.

Syntaksa:

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

Parametry:

filename: Dospołne mjeno wudawanskeje dataje w notaciji FileSystem.FileNaming.

header: Komentary, kotrež so horjeka w generowanej POT-dataji přidawaja.

Njewužiwajće načolne znamješka „#“. Jeli chceće, zo so hłowa do wjacorych linkow rozdźěluje, zasadźće sekwency escape (\n), jeli trjeba. Standardna hódnota so hromadźe z tekstom přidawa, kotryž je w argumenće header podaty.

encoding: Znamješkowa sadźba, kotraž so ma wužiwać (standard = "UTF-8").

Přikład:


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

Generowana dataja měła přikaz GNU msgfmt --check wuspěšnje přepodać.

GetText

Wotwołuje přełoženy znamješkowy rjećazk, kotryž podatemu argumentej msgid wotpowěduje.

Lisćina argumentow móže so podać, zo by zastupowace symbole (%1, %2 …) w znamješkowym rjećazku podała.

Jeli so njepřełoženy znamješkowy rjećazk njenamaka, metoda njepřełoženy znamješkowy rjećazk wróći, po tym zo běchu so zastupowace symbole z podatymi argumentami wuměnili.

Syntaksa:

Tuta metoda da so pak přez dospołne mjeno GetText pak přez skrótšenku _ (jednotliwa podsmužka) wuwołać:

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

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

W bibliotece ScriptForge su wšě metody, kotrež so ze znamješkom „_“ započinaja, jenož za interne wužiwanje rezerwowane. Skrótšenka _, kotraž za GetText wužiwa, je jeničke wuwzaće za tute prawidło, dokelž da so wěsće w skriptach Basic a Python wužiwać.

Parametry:

msgid: Njepřełoženy znamješkowy rjećazk, kotryž je tekst, kotryž so w programowym kodźe jewi. Njesmě prózdny być. Móže rjad zastupowacych symbolow (%1 %2 %3 …) wobsahować, kotrež dadźa so wužiwać, zo bychu tekst dynamisce we wuwjedźenskim času zasadźili.

Nimo wužiwanja jednotliweho znamješkoweho rjećazka msgid tuta metoda tež slědowace formaty akceptuje:

Znamješkowy rjećazk context, z kotrymž metoda msgid w PO-dataji wotwołuje, abo;
Kombinacija context|msgid, kotraž metodu instruuje, msgid z pomocu podateje hódnoty context wotwołać. Druhi dźěl argumenta so wužiwa, zo by čitajomnosć koda polěpšił.

args: Hódnoty, kotrež so maja do zastupowacych symbolow zasadźić. Kóždy wariablowy typ je dowoleny, ale jenož znamješkowe rjećazki, ličby a datumy so wobkedźbuja.

Přikład:

W Basic

Předstajće sej, zo slědowacy kod so na instalaciji %PRODUCTNANE z narodnej šemu „es-ES“ wuwjedźe. Nimo toho je dataja „es-ES.po“ w podatym rjadowaku, kotraž znamješkowy rjećazk přełožuje, kotryž so na metodu GetText přepodawa:


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

W Python


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

Wšě rutiny Basic ScriptForge abo identifikatory, kotrež so z podsmužku „_“ započinaja, su za interne wužiwanje wuměnjene. Njejsu za to myslene, so w makrach Basic abo skriptach Python wužiwać.

Słužba ScriptForge.FileSystem

Přełožowanje wodźenskich elementow w dialogowym editorje