Tjenesten ScriptForge.L10N

Denne tjeneste leverer et antal metoder i forbindelse med oversættelse af strenge med minimal indvirkning på programmets kildekode. Metoderne, der er leveret af tjenesten L10N kan hovedsagelig bruges til:

• Opret POT-filer, der kan bruges som skabeloner til oversættelse af alle strenge i programmet.

• Få oversatte strenge under kørslen til det sprog, der er defineret i egenskaben Locale.

Akronymet L10N står for Lokalisering og henviser til et sæt procedurer for oversættelse af software til et bestemt land eller region.

PO-filer er længe blevet fremmet i fællesskabet for fri software som et middel til at levere flersprogede brugerflader. Dette er opnået gennem brug af menneskeligt læsbare tekstfiler med en veldefineret struktur, som på ethvert givet sprog angiver strengen på kildesproget og den oversatte streng.

Den største fordel ved PO-formatet er adskillelsen af programmøren og oversætteren. PO-filer er uafhængige tekstfiler, så programmøren kan sende POT-skabelonfiler til oversætterne, som så oversætter indholdet i dem og sender de oversatte PO-filer på hvert enkelt understøttet sprog tilbage.

Tjenesten L10N er baseret på GNU-implementeringen af PO (portable object)-filer. For at vide mere om dette filformat besøger du GNU gettext Utilities: PO Files.

Denne tjeneste implementer metoderne oplistet herunder:

• AddText (TilføjTekst): Bruges af programmøren til at opbygge et sæt strenge, der bliver oversat senere.

• AddTextsFromDialog: Udtrækker alle strenge fra en forekomst af tjenesten Dialog.

• ExportToPOTFile-fil (Eksporter Til POT-fil): Eksporterer strenge, tilføjet med metoden TilføjTekst til en POT-fil.

• GetText (Hent Tekst): Henter de oversatte strenge under kørsel.

Bemærk, at de første to metoder bruges til at opbygge et sæt strenge til oversættelse og eksportere dem til POT-fil. Det er imidlertid ikke obligatorisk at oprette POT-filer med disse metoder. Efter som det er tekstfiler, kunne programmøren have oprettet med en vilkårlig tekstredigering.

Kald af tjeneste

Før brug af tjenesten L10N skal biblioteket ScriptForge være indlæst eller importeret:

• Basic-makroer kræver, at biblioteket ScriptForge indlæses med følgende udtryk:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Python-scripts kræver import af scriptforge-modulet:
from scriptforge import CreateScriptService

Der er flere måder at kalde tjenesten L10N på med op til fem friviliige argumenter, der angiver den mappe, hvor PO-filerne gemmes, den lokalisering og den indkodning, der skal bruges, såvel som en tilbagefalds PO-fil og dens indkodning.

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

mappenavn: Mappen, der indeholder PO-filerne. Den skal udstrykkes i notationen FileSystem.FileNaming (Filsystem.Filnavngivelse).

lokalisering: En streng i form af "la-CO " (language-COUNTRY = sprog-LAND) er form af "la" (language = sprog) alene.

indkodning: Det tegnsæt, der skal bruges. Standardindkodningen er "UTF-8".

lokalisering2: En streng, der angiver den reserve-lokalisering, der skal bruges, hvis den PO-fil, der svarer til den definerede locale (lokalisering)s-parameter ikke eksisterer. Denne parameter udtrykkes på formen "la-CO" (language-COUNTRY = Sprog-LAND) eller "la" (language = sprog) alene.

indkodning2: Det tegnsæt, i reserve-PO-filen, der svarer til argumentet locale2. Standardindkodningen er "UTF-8".

To learn more about the names of character sets, visit IANA's Character Set page. Be aware that LibreOffice does not implement all existing character sets.

Det følgemde eksempel instantierer tjenesten L10N uden nogen valgfrie argumenter. Dette aktiverer udelukkende metoderne AddText (Tilføj_tekst) og ExportToPOTFile (Eksporter_ til_POT-fil), hvilket er nyttigt til oprettelse af POT-filer.

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

Eksemplet herunder angiver den mappe, der indeholder PO-filerne. Da lokalisationen ikke der defineret, benytter tjenesteeksemplaret den lokalisring, der er defineret til LibreOffice-brugerfladen, som er den samme lokalisering, som er defineret i egenskaben OfficeLocale i tjenesten Platform (platform).

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

Eksemplet herover resulterer i en afviklingsfejl, hvis PO-filen, der svarer til lokaliseringen OfficeLocale ikke findes i den angivne mappe.

I eksemplet herunder er lokaliseringen udtrykkelig angivet som belgisk-fransk ("fr-BE"), hvorfor tjeneste vil indlæse filen "fr-BE.po" fra mappen "C:\\myPOFiles". Hvis filen ikke findes, sker der en fejl.

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

For at undgå fejl er det muligt, at angive en foretrukket og en reserve-lokalisering og -indkodning. Det følgende eksempel forsøger først at at indlæse filen "fr-BE.po". fra den angivne mappe og, hvis den ikke eksister, indlæses filen "en-US.po".

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

PO-filer skal navngives på formen "la-CO.po" eller "la.po", hvor "la" henviser til sproget og "CO" er landet. Nogle eksempler: "en-US.po", "fr-BE.po" eller "fr.po".

Det anbefales af frigøre ressourcer efter brug:

      Set myPO = myPO.Dispose()
    

Eksemplerne herover kan oversættes til Pythonsom 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()
    

Der kan findes flere forekomster af tjenesten L10N på samme enhed. Hver forekomst skal imidlertid bruge en særskilt mappe til sine PO-filer.

Egenskaber

AddText

Tilføjer et nyt element til listen over strenge, der kan lokaliseres. De må endnu ikke eksistere.

Metoden returnerer True (sand), hvis den lykkes.

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

kontekst: Nøglen, der skal hente den oversatte streng med metoden GetText (hent_ tekst). Denne parameter har en standardværdi på "".

msgid: Den uoversatte streng, som er den tekst, der ses i programkoden. Den må ikke være tom. Msgid bliver nøglen til ar hente den oversatte streng gennem metoden GetText (hent_tekst), når context (konteksten) er tom.

Strengen msgid kan indeholde et vilkårligt antal pladsholdere (%1 %2 %3 ...) til dynamisk at modificere strengen på kørselstidspunktet.

kommentar: Valgfri kommentar, der skal tilføjes sammen med strengen for at hjælpe oversættere.

Eksemplet herunder opretter et sæt strenge 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

Udtrækker automatisk strenge fra en dialog og tilføjer dem til listen over lokaliserede tekststrenge. Følgende strenge udtrækkes:

• Dialogens titel.

• Overskrift til følgende kontroltyper: Knap, Afkrydsningsfelt, Fast_linje, Fast_tekst, Gruppefelt og Alternativknap.

• Statiske strenge i Listefelter og Kombinationsfelter.

• Det værktøjstip eller den hjælpetekst, der vises, når musen svæver over kontrolfeltet.

Metoden returnerer True (sand), hvis den lykkes.

Den dialog, som strengene skal udtrækkes fra; må ikke være åben, når metoden kaldes.

Når en forekomst af tjenesten L10N oprettes fra en eksisterende PO-fil, bruger du metoden GetTextsFromL10N (hent_tekster_fra_L10N) fra tjenesten Dialogfor automatisk at indlæse alle oversatte strenge i dialogen.

svc.AddTextsFromDialog(dialog: svc): bool

dialog: en forekomst af tjenesten Dialog, svarende til den dialog, som strengene skal udtrækkes fra.

Følgende eksempler udtrækker alle strenge fra dialogen "MyDialog" gemt i biblioteket "Standard" og eksportere dem til en POT-fil:

      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

Eksporterer et sæt af ikke-oversatte strenge som en POT-fil.

For at bygge et sæt strenge, kan du bruge enten en række AddText (tilføj_tekst)-metodekald, eller med en vellykket påkaldelse af tjenesten L10N med argumentet foldername (mappenavn). Det er også muligt at bruge en kombination af begge teknikker.

Metoden returnerer True (sand), hvis den lykkes.

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

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

overskrift: Kommentarer, der bliver tilføjet oven på den genererede POT-fil.

Brug ikke nogen indledende "#"-tegn. Hvis du opbryde overskriften i flere linjer, indsætter du escape-sekvenser (\n), hvor det er relevant. En standard-overskrift bliver tilføjet ved siden af den tekst, der er angivet i argumentet header (overskrift).

indkodning: tegnsættet, der skal bruges (Standard = "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')
    

Den genererede fil bør kunne klare GNU-kommandoen msgfmt --check.

GetText

Henter den oversatte streng, der svarer til det givne msgid-argument.

Der kan angives en liste over argumenter, der kan erstatte pladsholderne (%1, %2, ...) i strengen.

Hvis der ikke findes en oversat streng, returnerer metoden den ikke-oversatte streng, efter at pladsholderne er erstattet med de angivne argumenter.

Denne metode kan kaldes enten med sit fulde navn GetText (Hent tekst) eller med genvejen _ (en enkelt understregning):

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

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

I biblioteket ScriptForge er alle metoder, der starter med tegnet "_" reserveret til udelukkende internt brug. Genvejen _, der bruges i stedet for GetText (hent_tekst), er imidlertid en eneste undtagelse fra denne regel, derfor kan den anvendes sikkert i Basic- og Python-scripts.

msgid: Den uoversatte streng, som er den tekst, der vises i programkoden. Den må ikke være tom. Den kan indeholde et vilkårligt antal pladsholdere (%1 %2 %3 ...), der kan bruges til dynamisk at indsætte tekst på kørselstidspunktet.

Udover at bruge en enkelt msgid-streng, accepterer også denne metode også følgende formater:

• Strengen context med hvilken metoden vil hente msgid i PO-filen, eller;

• Kombinationen context|msgid (kontekst|msgid), der instruerer metoden om at hente msgiden med en angivet context-værdi. Den anden del af argumentet bruges til at forbedre kodens læselighed.

args: Værdier, der indsættes i pladsholderne. Enhver type variabel er tillads, imidlertid tages kun strenge, tal og datoer i betragtning.

Antag, at følgende kode kører på en LibreOffice-installation med lokalisationen sat til "es-ES". Desuden er der en fil "es-ES.po" i den angivne mappe, der oversætter strengen, der videregives til metoden GetText (Hent tekst):

      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 Basic-rutiner eller identifikatorer, der er indledet med et understreget tegn "_" er reserveret til internt brug. Det er ikke meningen, at de skal bruges i Basic-makroer eller Python-scripts.