ScriptForge.L10N service

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.

The L10N service is based on the GNU implementation of PO (portable object) files. To learn more about this file format, visit 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

To invoke the L10N service, two optional arguments can be specified to determine the folder where PO files are located and the locale to be used, as described below.

CreateScriptService("L10N", foldername: str, locale: str): 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).

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

The following example instantiates the L10N service without any optional arguments. This will only enable the AddText and ExportToPOTFile methods.

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

The example below specifies the folder containing the PO files. Because the locale is not defined, the service instance will use the current Collabora Office locale settings.

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

The example above will result in an runtime error if the PO file for the current locale does not exist in the specified folder.

In the example below, both the folder name and locale settings are explicitly defined to be Belgian French.

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

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

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 = myPO.Dispose()
    

Egenskaper

AddText

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

Metoden returnerer Sann hvis vellykket.

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

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.

Eksemplet nedenfor lager et sett med strenger på engelsk:

      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

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.

When a L10N service instance is created from an existing PO file, use the GetTextsFromL10N method from the Dialog service to automatically load all translated strings into the dialog.

svc.AddTextsFromDialog(dialog: svc): bool

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

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

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

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

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

filnavn: Utdatafilen i FileSystem.FileNaming notasjon.

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

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

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.

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.

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.

Tenk på at følgende kode kjører på en Collabora Office-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"
    

      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.