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

Before using the L10N service the ScriptForge library needs to be loaded or imported:

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


There are several ways to invoke the L10N service using up to five optional arguments that specify the folder where PO files are stored, the locale and encoding to be used, as well as a fallback PO file and its encoding.

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.

encoding: The character set to be used. The default encoding is "UTF-8".

locale2: A string specifying the fallback locale to be used in case the PO file corresponding to the locale defined the locale parameter does not exist. This parameter is expressed in the form "la-CO" (language-COUNTRY) or "la" (language) only.

encoding2: The character set of the fallback PO file corresponding to the locale2 argument. The default encoding is "UTF-8".

note

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


Eksempel:

I Basic

The following example instantiates the L10N service without any optional arguments. This will only enable the AddText and ExportToPOTFile methods, which is useful for creating POT files.


      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 locale defined for the LibreOfficeDev user interface, which is the same locale defined in the OfficeLocale property of the Platform service.


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

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


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

To avoid errors, it is possible to specify a preferred and a fallback locale and encoding. The following example will first try to load the file "fr-BE.po" from the specified folder and if it does not exist, the file "en-US.po" will be loaded.


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