Innhald
Innhaldsliste 🔎︎

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

This service implements the methods listed below:

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

- AddTextsFromDialog: Extracts all strings from a Dialog service instance.

- 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

Viss du vil kalla opp tenesta L10N, kan du gje to valfrie argument for å bestemma mappa som PO-filene er plasserte i og dei nasjonale innstillingane som skal brukast, som forklart nedanfor.

### Syntaks:

CreateScriptService("L10N", foldername: str, locale: str): svc

foldername: The folder containing the PO files. It must be expressed in the FileSystem.FileNaming notation.

locale: A string in the form "la-CO" (language-COUNTRY) or in the form "la" (language) only.

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

### Eksempel:

##### I Basic

Eksempelet nedanfor startar tenesta L10N utan valfrie argument. Dette aktiverer berre metodane AddText (LeggTilTekst) og ExportToPOTFile (EksporterTilPOT-fil).

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

Eksemplet nedanfor gjev mappa som inneheld PO-filene. Sidan den nasjonale innstillinga ikkje er definert, vil førekomsten av tenesta bruka dei gjeldande nasjonale innstillingane for LibreOffice.

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

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

I eksempelet nedanfor er både mappenamnet og nasjonale innstillingar eksplisitt definert som belgisk fransk.

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

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 «fr.po».

Det vert tilrådd å frigje ressursar etter bruk:

          Set myPO = myPO.Dispose()

##### I Python

The examples above can be translated to Python as follows:

          from scriptforge import CreateScriptService
          myPO = CreateScriptService('L10N')

          myPO = CreateScriptService('L10N', r'C:\myPOFiles')

          myPO = CreateScriptService('L10N', r'C:\myPOFiles', 'fr-BE')
          myPO = myPO.Dispose()

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

The method returns True if successful.

### Syntaks:

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

### Parametrar:

context: The key to retrieve the translated string with the GetText method. This parameter has a default value of "".

msgid: The untranslated string, which is the text appearing in the program code. It must not be empty. The msgid becomes the key to retrieve the translated string via GetText method when context is empty.

The msgid string may contain any number of placeholders (%1 %2 %3 ...) for dynamically modifying the string at runtime.

comment: Optional comment to be added alongside the string to help translators.

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

Automatically extracts strings from a dialog and adds them to the list of localizable text strings. The following strings are extracted:

- The title of the dialog.

- The caption of the following control types: Button, CheckBox, FixedLine, FixedText, GroupBox and RadioButton.

- Static strings in ListBoxes and ComboBoxes.

- The tooltip or help text displayed when the mouse hovers over the control.

The method returns True if successful.

The dialog from which strings will be extracted must not be open when the method is called.

When a L10N service instance is created from an existing PO file, use the GetTextsFromL10N method from the Dialog service to automatically load all translated strings into the dialog.

### Syntaks:

svc.AddTextsFromDialog(dialog: svc): bool

### Parametrar:

dialog: a Dialog service instance corresponding to the dialog from which strings will be extracted.

### Eksempel:

The following example extracts all strings from the dialog "MyDialog" stored in the "Standard" library and exports them to a POT file:

##### 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 eit sett med ikkje omsette strengar som ei POT-fil.

To build a set of strings you can use either a succession of AddText method calls, or by a successful invocation of the L10N service with the foldername argument present. It is also possible to use a combination of both techniques.

The method returns True if successful.

### Syntaks:

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

### Parametrar:

filename: The output file in FileSystem.FileNaming notation.

header: Comments that will be added on top of the generated POT file.

Do not include any leading "#" characters. If you want the header to be broken into multiple lines, insert escape sequences (\n) where relevant. A standard header will be added alongside the text specified in the header argument.

encoding: The character set to be used (Default = "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')

Den genererte fila må bestå GNU-kommandoen msgfmt --check.

## GetText

Gets the translated string corresponding to the given msgid argument.

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

In the ScriptForge library, all methods starting with the "_" character are reserved for internal use only. However, the shortcut _ used for GetText is the only exception to this rule, hence it can be safely used in Basic and Python scripts.

### Parametrar:

msgid: The untranslated string, which is the text appearing in the program code. It must not be empty. It may contain any number of placeholders (%1 %2 %3 ...) that can be used to dynamically insert text at runtime.

Besides using a single msgid string, this method also accepts the following formats:

- The context string with which the method will retrieve the msgid in the PO file, or;

- A combination context|msgid, instructing the method to retrieve the msgid using specified context value. The second part of the argument is used to improve code readability.

args: Values to be inserted into the placeholders. Any variable type is allowed, however only strings, numbers and dates will be considered.

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