Innhald

# Tenesta ScriptForge.L10N

Denne tenesta inneheld ei rekkje metodar knytt til omsetjinga av strengar med minimal innverknad på kjeldekodane for programmet. Metodane som er leverte av tenesta L10N kan i hovudsak brukast til å:

- Laga POT-filer som kan brukast som malar for omsetjing av alle strengane i programmet.

- Henta omsette strengar under køyringa for det språket som er definert i eigenskapen Locale.

Akronymet L10N står for lokalisering og refererer til eit sett med prosedyrar for oversetting av programvare til eit bestemt land eller region.

PO-filer har lenge vore promoterte i det gratis programvarefellesskapet som eit middel for å levera fleirspråklege brukargrensesnitt. Dette vert oppnådd ved bruk av lesbare tekstfiler med ein veldefinert struktur som for eit gjeve språk spesifiserer kjeldespråkstrengen og den lokaliserte strengen.

Den største fordelen med PO-formatet er åtskiljinga av programmeraren og omsetjaren. PO-filer er uavhengige tekstfiler, slik at programmeraren kan senda POT-malfiler til omsetjarar, som deretter vil omsetja innhaldet og returnere dei omsette PO-filene for kvart støtta språk.

Tenesta L10N er basert på GNU-implementering av PO (portable object)-filer. Du kan finna meir om dette filformat i GNU gettext Utilities: PO Files.

Denne tenesta implementerer desse metodane:

- AddText (Legg til tekst): Vert brukt av programmeraren til å byggja eit sett med strengar som skal omsetjast seinare.

- AddTextsFromDialog: Trekkjer ut alle strengane frå ein førekomst av tenesta Dialog.

- ExportToPOTFile-fil (EksporterTilPOT-fil): Eksporterer strengar lagt til med metoden AddText til ei POT-fil.

- GetText (HentTekst): Hentar dei omsette strengane under køyringa.

Legg merkje til at dei to første metodane vert brukte til å byggja eit sett med overførbare strengar og eksportera dei til ei POT-fil. Det er likevel ikkje heilt nødvendig å laga POT-filer ved hjelp av desse metodane. Sidan dei er tekstfiler, kunne programmeraren ha laga dei ved hjelp av kva tekstredigeringsprogram som helst.

## Oppkall av tenester

Før du brukar tenesta L10N, må biblioteket ScriptForge vera lasta inn eller importert:

• Grunnleggjande makroar krev innlasting av biblioteket ScriptForge ved hjelp av denne setninga:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")
• Python-skript krev import frå scriptforge-modulen:
from scriptforge import CreateScriptService

Du kan kalla opp tenesta L10N med opp til fem valfrie argument som spesifiserer mappa som PO-filene er lagra i, den lokaliseringa og kodinga som skal brukast og reserve PO-fila og kodinga av denne.

### Syntaks:

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

foldername: Mappa som inneheld PO-filene. Namnet må oppfylla krava i FileSystem.FileNaming.

locale: Ein streng på forma «la-CO» (language-COUNTRY = språk-LAND) eller på form «la» (language = språk).

encoding: Teiknsettet som skal brukast. Standardkodinga er «UTF-8».

locale2: Ein streng som spesifiserer reservelokaliteten som skal brukast i tilfelle PO-fila som svarar til lokaliteten definert i locale-parameteren ikkje finst. Denne parameteren vert berre uttrykt i form "la-CO" (språk-LAND) eller "la" (språk).

koding2: Teiknsettet til reserve-PO-fila som svarar til lokale2-argumentet. Standard er «UTF-8»

Du kan finna meir om namna på teiknsetta i IANAs tegnsett. Ver merksam på at LibreOffice ikkje implementerer alle teiknsetta som finst.

### Eksempel:

##### I Basic

Eksempla nedanfor set opp tenesta L10N utan valfrie argument. Dette vil berre aktivera metodane AddText og ExportToPOTFile, som er nyttig for å laga POT-filer.

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

Eksempelet nedanfor spesifiserer mappa som inneheld PO-filene. Fordi lokaliteten ikkje er definert, vil tenesteførekomsten bruka lokaliteten som er definert for LibreOffice-brukargrensesnittet, som er den same lokaliteten som er definert i OfficeLocale-eigenskapen til Plattform-tenesta.

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

Eksempelet ovanfor vil føra til ein køyretidsfeil viss PO-fila som svarar til lokaliteten OfficeLocale ikkje finst i den gjevne mappa.

I eksempelet nedanfor er den nasjonale innstillinga eksplisitt definert som belgisk fransk (\"fr-BE\"), slik at tenesta lastar inn fr-BE.po-fila frå mappa C:\\myPOFiles. Viss fila ikkje finst, kjem det ei feilmelding.

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

For å unngå feil, er det mogleg å gjeva ei føretrekt og ei reserveinnstilling og koding. Følgjande eksempel prøver først å lasta inn fila fr-BE.po frå den gjevne mappa, og viss ho ikkje finst, vert fila en-US.po lasta inn.

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

PO-filer må namngjevast i forma «sp-LA.po» eller «sp.po», der «sp» refererer til språket og «LA» er landet. Nokre eksempel er: «en-US.po», «fr-BE.po» eller «nn.po».

Det vert tilrådd å frigje ressursar etter bruk:

          Set myPO = myPO.Dispose()

##### I Python

Eksempla ovanfor kan omsetjast til Python slik:

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

Det kan vera fleire tilfelle av tenesta L10N i same eining. Kvar førekomst skal likevel ha ei særskild mappe til PO-filene.

## Eigenskapar

Namn | Skriveverna | Type | Beskriving
--- | --- | --- | ---
Folder | Ja | String | Mappa som inneheld PO-filene (sjå eigenskapen FileSystem.FileNaming (FileSystem.FilnaNaming) for å læra meir om den brukte notasjonen).
Languages | Ja | Array | Ei nullbasert matrise som viser alle basisnamna (utan filtypen «po») for PO-filene som finst i den gjevne Mappa.
Locale | Ja | String | Den gjeldande språk-LAND-kombinasjonen. Denne eigenskapen vil i utgangspunktet vera tom viss tenesta byrja utan nokre av dei valfrie argumenta.

Liste over metodar i tenesta L10N
AddText AddTextsFromDialog | ExportToPOTFile | GetText

## AddText

Legg til ei ny oppføring i lista over strengar som kan lokaliserast. Oppføringa må ikkje finnast frå før.

Metoden returnerer Sann viss han lukkast.

### Syntaks:

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

### Parametrar:

context: Nøkkelen for å henta den omsette strengen med metoden GetText . Denne parameteren har standardverdien "".

msgid: Den ikkje omsette strengen, som er teksten som finst i programkoden. Denne må ikkje vera tom. msgid vert nøkkelen for å henta den omsette strengen ved hjelp av metoden GetText når context er tom.

Strengen msgid kan innehalda kor mange plasshaldarar som helst (%1 %2 %3 …) for dynamisk endring av strengen under køyring.

comment: Valfri merknad som vert lagt til ved sida av strengen for å hjelpa omsetjarane.

### Eksempel:

Eksempelet nedanfor lagar eit sett med strengar 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

Trekkjer automatisk ut strengar frå eit dialogvindauge og legg dei til i lista over tekststrengar som kan lokaliserast. Desse strengane vert trekte ut:

- Tittelen på dialogvindauget.

- Tittelen på desse kontrollelementtypane: knapp avkryssingsfelt, fast linje, fast tekst, gruppefelt og radioknapp.

- Statiske strengar i listefelt og kombinasjonsfelt.

- Den hjelpebobla eller hjelpteksten som kjem fram når musepeikaren vert halde over kontrollelementet.

Metoden returnerer Sann viss han lukkast.

Dialogvindauget som strengane skal trekkjast ut frå, må ikkje vera open når metoden vert kalla opp.

Når ein førekomst av tenesta L10N vert laga frå ri PO-fil som finst frå før, brukar du metoden GetTextsFromL10N frå tenesta Dialog for automatisk å lesa inn alle omsette strengar i dialogvindauget.

### Syntaks:

svc.AddTextsFromDialog(dialog: svc): bool

### Parametrar:

dialog: ein førekomst av tenesta Dialog som svarar til det dialogvindauget som strengane skal trekkjast ut frå.

### Eksempel:

Dei neste eksempla trekkjer alle strengane ut frå dialogvindauget "MyDialog" som er lagra i biblioteket "Standard" og eksporterer dei til ei 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 eit sett med ikkje omsette strengar som ei POT-fil.

For å byggja eit sett med strengar, kan du bruka anten ei rekkje oppkall av metoden AddText, eller ved ei vellukka aktivering av L10N-tenesta med foldername-argumentet. Det er også mogleg å bruka ein kombinasjon av begge teknikkane.

Metoden returnerer Sann viss han lukkast.

### Syntaks:

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

### Parametrar:

filename: Heile namnet tl utdata-fila i FileSystem.FileNaming-notasjonen.

header: merknadar som vert lagde til øvst i den genererte POT-fila.

Ikkje ta med innleiande #-teikn. Viss du vil dela overskrifta på fleire linjer, set du inn escape-sekvensen (\n) der det passar. Det vert lagt til ei standardoverskrift ved sida av teksten som er gjeve i argumentet header.

encoding: Teiknsettet som skal brukast (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 genererte fila må bestå GNU-kommandoen msgfmt --check.

## GetText

Hentar den omsette strengen som svarar til det gjevne argumentet msgid.

Det kan setjast opp ei liste over argument som kan erstatta plasshaldarane (%1, %2, ...) i strengen.

Viss det ikkje finst ein omsett streng, returnerer metoden den ikkje-omsette strengen etter å ha bytt ut plasshaldarane med dei gjevne argumenta.

### Syntaks:

Denne metoden kan kallast opp anten ved hjelp av det fullstendige namnet GetText eller med snarvegen _ (eit enkelt understrekingsteikn):

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

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

I ScriptForge-biblioteket er alle metodar som byrjar med teiknet «_», reserverte for intern bruk. Snarvegen _ som vert brukt i GetText er det einaste unntaket frå denne regelen, og kan såleis trygt brukast i Basic-skript.

### Parametrar:

msgid: Den ikkje-omsette strengen, som er teksten som vert vist i programkoden. Denne må ikkje vera tom. Han kan innehalda kor mange plasshaldarar (%1 %2 %3 ...) som helst som kan brukast til å setja inn tekst dynamisk under køyringa.

I tillegg til å bruka ein enkeltmsgid-streng, godtar denne metoden også desse formata:

- Strengen context som metoden brukar til å henta msgid i PO-fila, eller;

- Ein kombinasjon contekst| msgid som seier at metoden skal henta msgid ved hjelp av gjeven contekst-verdi. Den andre delen av argumentet vert brukt til å gjera koden lettare å lesa.

args: Verdiar som skal setjast inn i plasshaldarane. Alle variabeltypar er tillatne, men berre strengar, tal og datoar vil vert tekne omsyn til.

### Eksempel:

##### I Basic

Gå ut frå at denne koden køyrer på ein LibreOffice-installasjon med nasjonale innstillingar sett til «es-ES». I tillegg er det ei fil «es-ES.po» inne i den gjevne mappa som omset strengen som vert sendt til metoden GetText:

          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-rutinane og -identifikatorane som vert innleidde med understrek «_» er reserverte for internt bruk. Dei er ikkje meint brukte i Basic-makroar.

Liknande emne

Tenesta ScriptForge.FileSystem

Omsetjing av kontrollelement i redigeringsprogrammet for dialogvindauge