ScriptForge.L10N tjeneste

Denne tjenesten gir en rekke metoder knyttet til oversettelse av strenger med minimal innvirkning på programmets kildekode. Metodene som tilbys av L10N-tjenesten kan hovedsakelig brukes til å:

Lag POT-filer som kan brukes som maler for oversettelse av alle strenger i programmet.
Få oversatte strenger under kjøring for språket som er definert i egenskapen Lokal.

Akronymet L10N står for lokalisering og refererer til et sett med prosedyrer for å oversette programvare til et bestemt land eller område.

PO-filer har lenge vært fremmet i friprogramvarefellesskapet som et middel til å tilby flerspråklige brukergrensesnitt. Dette oppnås ved bruk av menneskelesbare tekstfiler med en veldefinert struktur som spesifiserer, for et gitt språk, kildespråkstrengen og den lokaliserte strengen.

Hovedfordelen med PO-formatet er dissosiasjon av programmereren og oversetteren. PO-filer er uavhengige tekstfiler, så programmereren kan sende POT-malfiler til oversettere, som deretter vil oversette innholdet og returnere de oversatte PO-filene for hvert støttet språk.

L10N-tjenesten er basert på GNU-implementeringen av PO (portable object)-filer. For å lære mer om dette filformatet, besøk GNU gettext Utilities: PO Files .

Denne tjenesten implementerer metodene som er oppført nedenfor:

AddText: Brukes av programmereren til å bygge et sett med strenger som vil bli oversatt senere.
AddTextsFromDialog: Trekker ut alle strenger fra en Dialog tjenesteforekomst.
ExportToPOTFile: Eksporterer strengene lagt til med AddText-metoden til en POT-fil.
GetText: Henter de oversatte strengene under kjøring.

Merk at de to første metodene brukes til å bygge et sett med oversettbare strenger og eksportere dem til en POT-fil. Det er imidlertid ikke obligatorisk å lage POT-filer ved hjelp av disse metodene. Siden de er tekstfiler, kunne programmereren ha laget dem ved hjelp av et hvilket som helst tekstredigeringsprogram.

Tjenestepåkallelse

Før du bruker L10N-tjenesten, må ScriptForge-biblioteket lastes eller importeres:

• Grunnleggende makroer krever å laste ScriptForge-biblioteket ved hjelp av følgende setning:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Python-skript krever import fra scriptforge-modulen:
fra scriptforge import CreateScriptService

Det er flere måter å påkalle L10N-tjenesten ved å bruke opptil fem valgfrie argumenter som spesifiserer mappen der PO-filer er lagret, lokaliteten og kodingen som skal brukes, samt en reserve-PO-fil og dens koding .

Syntaks:

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

mappenavn: Mappen som inneholder PO-filene. Det må uttrykkes i FileSystem.FileNaming-notasjonen.

locale: En streng i formen "la-CO" (språk-LAND) eller bare i formen "la" (språk).

koding: Tegnsettet som skal brukes. Standardkodingen er "UTF-8".

locale2: En streng som spesifiserer reservelokaliteten som skal brukes i tilfelle PO-filen som tilsvarer lokaliteten definert locale-parameteren ikke eksisterer. Denne parameteren uttrykkes kun i formen "la-CO" (språk-LAND) eller "la" (språk).

koding2: Tegnsettet til reserve-PO-filen som tilsvarer lokale2-argumentet. Standardkodingen er "UTF-8".

For å lære mer om navnene på tegnsett, besøk IANAs tegnsett side. Vær oppmerksom på at LibreOffice ikke implementerer alle eksisterende tegnsett.

Eksempel:

I Basic

Følgende eksempel instansierer L10N-tjenesten uten valgfrie argumenter. Dette vil bare aktivere metodene AddText og ExportToPOTFile, som er nyttig for å lage POT-filer.


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

Eksemplet nedenfor spesifiserer mappen som inneholder PO-filene. Fordi lokaliteten ikke er definert, vil tjenesteforekomsten bruke lokaliteten som er definert for LibreOffice-brukergrensesnittet, som er den samme lokaliteten som er definert i OfficeLocale-egenskapen til Plattform-tjeneste.


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

Eksemplet ovenfor vil resultere i en kjøretidsfeil hvis PO-filen som tilsvarer OfficeLocale-lokaliteten ikke eksisterer i den angitte mappen.

I eksemplet nedenfor er lokaliteten eksplisitt definert til å være belgisk fransk ("fr-BE"), derfor vil tjenesten laste filen "fr-BE.po" fra mappen "C:\myPOFiles". Hvis filen ikke eksisterer, vil det oppstå en feil.


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

For å unngå feil er det mulig å spesifisere en foretrukket og en reservelokale og koding. Følgende eksempel vil først prøve å laste filen "fr-BE.po" fra den angitte mappen, og hvis den ikke eksisterer, vil filen "en-US.po" lastes.


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

PO-filer må navngis i formen "la-CO.po" eller "la.po", der "la" refererer til språket og "CO" er landet. Noen eksempler er: "en-US.po", "fr-BE.po" eller "fr.po".

Det anbefales å frigjøre ressurser etter bruk:


      Set myPO = myPO.Dispose()

I Python

Eksemplene ovenfor kan oversettes til Python som følger:


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

Flere forekomster av L10N-tjenesten kan eksistere side om side. Hver forekomst må imidlertid bruke en egen katalog for sine PO-filer.

Egenskaper

Navn	Skrivebeskyttet	Type	Beskrivelse
Folder	Ja	String	Mappen som inneholder PO-filene (se egenskapen FileSystem.FileName for å lære om notasjonen som brukes).
Languages	Ja	Array	En null-basert matrise som viser alle basenavnene (uten ".po"-utvidelsen) til PO-filene som finnes i den spesifiserte mappen.
Locale	Ja	String	Den aktive språk-LAND-kombinasjonen. Denne egenskapen vil i utgangspunktet være tom hvis tjenesten ble instansiert uten noen av de valgfrie argumentene.

Liste over metoder i L10N-tjenesten
AddText AddTextsFromDialog	ExportToPOTFile	GetText

AddText

Legger til en ny oppføring i listen over lokaliserbare strenger. Det må ikke eksistere ennå.

Metoden returnerer Sann hvis vellykket.

Syntaks:

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

Parametre:

kontekst: Nøkkelen for å hente den oversatte strengen med GetText-metoden. Denne parameteren har en standardverdi på "".

msgstr: Den uoversatte strengen, som er teksten som vises i programkoden. Det må ikke være tomt. msgid blir nøkkelen til å hente den oversatte strengen via GetText-metoden når kontekst er tom.

msgid-strengen kan inneholde et hvilket som helst antall plassholdere (%1 %2 %3 ...) for dynamisk endring av strengen under kjøring.

kommentar: Valgfri kommentar som legges til ved siden av strengen for å hjelpe oversettere.

Eksempel:

Eksemplet nedenfor lager et sett med strenger på engelsk:

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

I 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

Trekker automatisk ut strenger fra en dialogboks og legger dem til listen over lokaliserbare tekststrenger. Følgende strenger trekkes ut:

Tittelen på dialogen.
Bildeteksten til følgende kontrolltyper: Button, CheckBox, FixedLine, FixedText, GroupBox og RadioButton.
Statiske strenger i ListBoxer og ComboBoxer.
Verktøytipset eller hjelpeteksten som vises når musen svever over kontrollen.

Metoden returnerer Sann hvis vellykket.

Dialogboksen som strenger skal trekkes ut fra må ikke være åpen når metoden anropes.

Når en L10N tjenesteforekomst opprettes fra en eksisterende PO-fil, bruk GetTextsFromL10N-metoden fra Dialog-tjenesten for automatisk å laste alle oversatte strenger inn i dialogboksen.

Syntaks:

svc.AddTextsFromDialog(dialog: svc): bool

Parametre:

dialog: en dialogtjenesteforekomst som tilsvarer dialogen som strenger skal trekkes ut fra.

Eksempel:

Følgende eksempel trekker ut alle strenger fra dialogboksen "MyDialog" som er lagret i "Standard"-biblioteket og eksporterer dem til en POT-fil:

I Basic


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

I Python


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

ExportToPOTFile

Eksporterer et sett med uoversatte strenger som en POT-fil.

For å bygge et sett med strenger kan du enten bruke en rekke AddText-metodekall, eller ved en vellykket påkalling av L10N-tjenesten med mappenavnet argument tilstede. Det er også mulig å bruke en kombinasjon av begge teknikkene.

Metoden returnerer Sann hvis vellykket.

Syntaks:

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

Parametre:

filename: The full output file name in FileSystem.FileNaming notation.

header: Kommentarer som legges til på toppen av den genererte POT-filen.

Ikke ta med noen innledende "#"-tegn. Hvis du vil at overskriften skal deles inn i flere linjer, setter du inn escape-sekvenser (\n) der det er relevant. En standard overskrift vil bli lagt til ved siden av teksten som er spesifisert i argumentet overskrift.

koding: Tegnsettet som skal brukes (Standard = "UTF-8").

Eksempel:


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

Den genererte filen skal bestå msgfmt --check GNU-kommandoen.

GetText

Henter den oversatte strengen som tilsvarer det gitte msgid argumentet.

En liste med argumenter kan spesifiseres for å erstatte plassholderne (%1, %2, ...) i strengen.

Hvis ingen oversatt streng blir funnet, returnerer metoden den uoversatte strengen etter å ha erstattet plassholderne med de angitte argumentene.

Syntaks:

Denne metoden kan kalles enten med det fulle navnet GetText eller ved snarveien _ (en enkelt understreking):

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

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

I ScriptForge-biblioteket er alle metoder som begynner med "_"-tegnet reservert kun for intern bruk. Imidlertid er snarveien _ brukt for GetText det eneste unntaket fra denne regelen, og kan derfor trygt brukes i Basic- og Python-skript.

Parametre:

msgstr: Den uoversatte strengen, som er teksten som vises i programkoden. Det må ikke være tomt. Den kan inneholde et hvilket som helst antall plassholdere (%1 %2 %3 ...) som kan brukes til å sette inn tekst dynamisk under kjøring.

I tillegg til å bruke en enkelt msgid-streng, godtar denne metoden også følgende formater:

kontekst-strengen som metoden vil hente msgid med i PO-filen, eller;
En kombinasjon context|msgid, som instruerer metoden for å hente msgid ved å bruke spesifisert context verdi. Den andre delen av argumentet brukes til å forbedre kodelesbarheten.

args: Verdier som skal settes inn i plassholderne. Enhver variabeltype er tillatt, men bare strenger, tall og datoer vil bli vurdert.

Eksempel:

I Basic

Tenk på at følgende kode kjører på en LibreOffice-installasjon med lokalitet satt til "es-ES". I tillegg er det en fil "es-ES.po" inne i den angitte mappen som oversetter strengen som sendes til GetText-metoden:


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

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

Alle ScriptForge Grunnleggende rutiner eller identifikatorer som er prefikset med et understrekingstegn "_" er reservert for intern bruk. De er ikke ment å brukes i grunnleggende makroer eller Python-skript.

ScriptForge.FileSystem-tjeneste

Oversetting av kontrollelementer i redigeringsprogrammet for dialogvinduer