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:

note

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.

tip

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:

note

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:

note

• Basic macros require to load ScriptForge library using the following statement:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Python scripts require an import from scriptforge module:
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.

Syntaks:

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

note

For at se mere om tegnsættenes navne besøger du sinden IANA's Character Set. Bemærk, at LibreOffice ikke implementerer alle eksisterende tegnsæt.


Eksempel:

I Basic

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

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

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

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

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

Navn

Readonly (Skrivebeskyttet)

Type (Type)

Beskrivelse

Folder

Yes (Ja)

String

Mappen, der indeholder PO-filerne (se egenskaben FileSystem.FileNaming (Filsystem.Filnavngivelse) for at fĂĄ mere at vide om den brugte notation).

Languages

Yes (Ja)

Array

En nul-baseret matrix, der oplister alle base-navnene (uden udvidelsen ".po") pĂĄ de PO-filer, der findes i den angivne Folder (Mappe).

Locale

Yes (Ja)

String

Den aktuelt aktive kombination af sprog-LAND. Denne egenskaber forbliver i begyndelsen tom, hvis tjenesten blev instantieret uden nogen af de valgfrie argumenter.


Liste over metoder i tjenesten L10N

AddText
AddTextsFromDialog

ExportToPOTFile

GetText


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.

Syntaks:

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

Parametre:

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.

Eksempel:

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

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

Metoden returnerer True (sand), hvis den lykkes.

note

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.

Syntaks:

svc.AddTextsFromDialog(dialog: svc): bool

Parametre:

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

Eksempel:

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

I Basic

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

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

Syntaks:

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

Parametre:

filename: Output-fil i notationen FileSystem.FileNaming (filsystem.filnavngivelse).

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

Eksempel:


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

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.

Syntaks:

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

note

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.


Parametre:

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:

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

Eksempel:

I Basic

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

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.


Støt os venligst!