Indhold
Indholdsfortegnelse 🔎︎

# 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 implementerer de tre metoder herunder:

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

- 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

For at kalde tjenesten L10N kan to frivillige argumenter angives for at bestemme den mappe, hvor PO-filerne er placeret, og den lokalisering, der skal bruges, som beskrevet herunder.

### Syntaks:

            CreateScriptService("L10N" [, FolderName As String [, Locale as String]])

FolderName (Mappenavn): Mappen, der indeholder PO-filerne. Det skal udtrykkes i notationen FileSystem.FileNaming.

Landestandard: En streng på formen "la-CO" (language-COUNTRY = sprog-LAND) eller blot på formen "la" (language = sprog).

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

Denne tjeneste er fuldt understøttet i sprogene Basic og Python. Alle eksempler udtrykkes med programmeringssproget Basic og kan let konverteres til Python.

### Eksempel:

Det følgende eksempel instantierer tjenesten L10N uden nogen valgfrie argumenter. Dette aktiverer kun metoderne AddText (Tilføj tekst) og ExportToPOTFile (Eksporter til POT-fil).

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

Eksemplet herunder angiver mappen, der indeholder PO-filerne. Fordi landestandarden ikke er defineret, anvender forekomsten af tjenesten de aktuelle LibreOffice landeindstillinger.

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

I eksemplet herunder er både mappenavnet og landestandarden udtrykkeligt defineret som belgisk fransk.

          Sæt myPO = CreateScriptService("L10N", "C:\myPOFiles\", "fr-BE")

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

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

## AddText

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

### Syntaks:

           myPO.AddText(Context As String, MsgId As String, [Comment As String]) As Boolean

### Parametre:

Context (Kontekst): Nøglen til at hente den oversatte streng med metoden GetText (Hent tekst). Denne parameter har standardværdien "".

MsgId: Den uoversatte streng, som er teksten, der ses i programkoden. Den må ikke være tom. MsgId bliver nøglen til at hente den oversatte streng ved hjælp af metoden GetText, når Context er tom.

Strengen MsgId (Besked ID) kan indeholde et antal pladsholdere (%1 %2 %3 ...) til dynamisk ændring af strengen under kørslen.

Comment (Kommentar): Valgfri kommentar, der tilføjes side om side med strengen for at hjælpe oversætterne.

### Eksempel:

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

## ExportToPOTFile

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

For at opbygge et sæt strenge kan du enten bruge en række kald af metoden AddText (tilføj tekst), eller et vellykket kald af tjenesten L10N med det udtrykte argument FolderName (Mappenavn). Det er også muligt at bruge en kombination af de to teknikker.

### Syntaks:

             myPO.ExportToPOTFile(FileName As String, [Header As String], [Encoding As String])

### Parametre:

FileName (Filnavn): Output-filen i notationen FileSystem.FileNaming (Filsystem.Filnavngivelse).

Header (Overskrift): Kommentarer, som bliver tilføjet øverst i den genererede POT-fil.

Medtag ingen indledende "#"-tegn. Hvis du vil have overskriften brudt op i flere linjer, indsætter du escape-sekvenser (\n), hvor det passer. En standardoverskrift bliver tilføjet sammen med teksten, der er angivet i argumentet Header (Overskrift).

Encoding (Tegnsæt): Tegnsættet, der skal bruges (Standard = "UTF-8").

### Eksempel:

             myPO.ExportToPOTFile("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 indhold i argumentet MsgId (Besked ID).

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

            myPO.GetText(MsgId As String[, Arg1[, Arg2[, ...]]]) As String
            myPO._(MsgId As String[, Arg1[, Arg2[, ...]]]) As String

I biblioteket ScriptForge er alle metoder, der begynder med tegnet "_" reserveret til udelukkende internt brug. Genvejen _, der bruges til GetText (hent tekst), er imidlertid den eneste undtagelse fra denne regel, derfor kan du trygt bruge den i Basic-scripts.

### Parametre:

MsgId (Besked ID): Den ikke-oversatte streng, som er teksten, der ses i programkoden. Den må ikke være tom. Den kan indeholde et vilkårligt antal pladsholdere (%1 %2 %3 ...), der kan bruges til dynamisk indsættelse af tekst under kørslen.

Udover brug af den enkelte streng MsgId (Besked ID), accepterer denne metode også følgende formater:

- Strengen Context (Kontekst), som metoden bruger til at hente MsgId (Besked ID) i PO-filen, eller;

- Kombinationen Context|MsgId (Kontekst|Besked ID), der instruerer metoden om at hente MsgId (Besked ID) med den angivne Context (Kontekst)-værdi. Den anden del af argumentet bruges til at forbedre kodens læselighed.

Arg1, ...: Værdier, der indsættes i pladsholderne. Enhver type variabel er tilladt, imidlertid tages udelukkende strenge, tal og dato i betragtning.

### Eksempel:

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:\MyPOFolder\")
          myPO.GetText("Welcome %1! Hope you enjoy this program", "John")
          ' "¡Bienvenido John! Espero que disfrutes de este programa"

Alle ScriptForge Basic-rutiner eller identifikatorer, som indledes med et understregningstegn "_" er reserveret til internt brug. De er ikke beregnet til brug i Basic-makroer.

Relaterede emner

Tjenesten ScriptForge.FileSystem

Oversættelse af Kontrolelementer i Dialog-redigeringen