ScriptForge.L10N-tjenesten

Indhold

# 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 afviklingen 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 instans af tjenesten Dialog.

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

- GetText (Hent Tekst): Henter de oversatte strenge på afviklingstidspunktet.

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 valgfrie argumenter, der angiver den mappe, hvor PO-filerne gemmes, den lokalisering (sprogindstilling) og den indkodning, der skal bruges, såvel som en reserve-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

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

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

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

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

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

For at lære mere om navnene på tegnsæt, se siden IANA's Character Set. Vær opmærksom på, 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 sprogindstillingen (lokaliseringen) ikke der defineret, benytter tjenesteeksemplaret den lokalisering, der er defineret til LibreOffice-brugerfladen, som er den samme lokalisering, som er defineret i egenskaben OfficeLocale i tjenesten 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 eksisterer, 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()

##### I Python

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

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

## Egenskaber

Navn | Skrivebeskyttet (Readonly) | 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 (lokal oversættelse)
AddText AddTextsFromDialog | ExportToPOTFile | GetText

## AddText

Tilføjer et nyt element til listen over strenge, der kan lokaliseres (vises på forskellige sprog). Elementet må ikke eksistere i forvejen.

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 ændre strengen på afviklingstidspunktet.

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 tekststrenge, som kan vises på forskellige sprog. Følgende strenge udtrækkes:

- Dialogens titel.

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

- Statiske strenge i rullelister 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 instans af tjenesten L10N oprettes fra en eksisterende PO-fil, bruger du metoden GetTextsFromL10N (hent_tekster_fra_L10N) fra tjenesten Dialog til automatisk at indlæse alle oversatte strenge i dialogen.

### Syntaks:

svc.AddTextsFromDialog(dialog: svc): bool

### Parametre:

dialog: en instans 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("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 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: Det fulde navn på output-filen i 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").

### 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 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

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å afviklingstidspunktet.

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.

### Eksempel:

##### I Basic

Antag, at følgende kode kører på en LibreOffice-installation med sprogindstillingen (lokaliseringen) 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"

Alle ScriptForge Basic-rutiner eller identifikatorer, der indledes med et understregstegn "_" er reserveret til internt brug. Det er ikke meningen, at de skal bruges i Basic-makroer eller Python-scripts.

Relaterede emner

Tjenesten ScriptForge.FileSystem

Oversættelse af kontrolelementer i Dialogeditoren

Støt os venligst!