Contenuto
Indice 🔎︎

# Servizio ScriptForge.L10N

Questo sevizio fornisce una serie di metodi relativi alla traduzione di stringhe con un impatto minimo sul codice sorgente del programma. I metodi forniti dal servizio L10N possono essere usati principalmente per:

- Creare file POT che possono essere usati come modelli per la traduzione di tutte le stringhe del programma.

- Ottenere in fase di esecuzione le stringhe tradotte nella lingua definita nella proprietà Locale.

La sigla L10N significa localizzazione e si riferisce ad un insieme di procedure di traduzione di software per uno specifico paese o regione.

I file PO sono stati promossi a lungo dalla comunità del software libero come mezzo per fornire interfacce utente multilingue. Questo si ottiene attraverso l'uso di file di testo, leggibili da esseri umani, con una struttura ben definita che specifica, per ogni linguaggio indicato, la stringa nella lingua sorgente e la stringa localizzata.

Il vantaggio principale del formato PO è la separazione dei ruoli di programmatore e traduttore. I file PO sono file di testo indipendenti, perciò il programmatore può inviare i modelli in file POT ai traduttori, che ne traducono i contenuti e restituiscono i file PO tradotti per ciascuna delle lingue supportate.

Il servizio L10N si basa sull'implementazione GNU dei file PO (portable object). Per saperne di più su questo formato di file, visitate GNU gettext Utilities: PO Files.

This service implements the methods listed below:

- AddText: Usato dal programmatore per costruire un insieme di stringhe che saranno tradotte in seguito.

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

- ExportToPOTFile: Esporta in un file POT le stringhe aggiunte dal metodo AddText.

- GetText: Ottiene le stringhe tradotte in fase di esecuzione.

Notate che i primi due metodi sono usati per costruire un insieme di stringhe da tradurre ed esportare in un file POT. Però non è obbligatorio creare file POT usando questi metodi. Trattandosi di file di testo, il programmatore può crearli usando qualsiasi editor di testo.

## Invocare il servizio

Invocando il servizio L10N, potete specificare, come descritto in seguito, due argomenti opzionali che determinano la cartella in cui si trovano i file PO file e la lingua da usare.

### Sintassi:

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.

Possono coesistere diverse istante del servizio L10N. Però ogni istanza deve usare una cartella separata per i relativi file PO.

### Esempio:

##### In Basic

L'esempio seguente istanzia il servizio L10N senza alcuna argomento opzionale. Questo attiverà solo i metodi AddText e ExportToPOTFile.

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

L'esempio seguente specifica la cartella che contiene i file PO. Dato che l'argomento locale non è definito, l'istanza del servizio userà le impostazioni locali correnti di 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.

Nell'esempio seguente, sia il nome della cartella che le impostazioni locali sono definiti esplicitamente per essere in francese del Belgio.

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

I file PO devono essere nominati nel formato "li-PA.po" o "li.po", dove "li" si riferisce alla lingua e "PA" è il paese. Alcuni esempi sono: "en-US.po", "fr-BE.po" o "fr.po".

Si raccomanda di liberare le risorse dopo l'uso:

          Set myPO = myPO.Dispose()

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

## Proprietà

Nome | Sola lettura | Tipo | Descrizione
Folder | Sì | String | La cartella contenente i file PO (per saperne di più sulla notazione usata controllate la proprietà FileSystem.FileNaming).
Languages | Sì | Array | Una matrice con indice di partenza zero che elenca tutte le basi dei nomi (senza l'estensione ".po") dei file PO che si trovano nella cartella (Folder) specificata.
Locale | Sì | String | La combinazione lingua-PAESE correntemente attiva. Questa proprietà sarà inizialmente vuota se il servizio è stato istanziato senza nessuno degli argomenti opzionali.

Elenco dei metodi del servizio L10N
AddText AddTextsFromDialog | ExportToPOTFile | GetText

## AddText

Aggiunge una nuova voce nell'elenco delle stringhe traducibili. Non deve esistere già.

The method returns True if successful.

### Sintassi:

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

### Parametri:

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.

### Esempio:

L'esempio seguente crea un insieme di stringhe in inglese:

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

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

### Sintassi:

svc.AddTextsFromDialog(dialog: svc): bool

### Parametri:

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

### Esempio:

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

##### In Basic

          oDlg = CreateScriptService("Dialog", "GlobalScope", "Standard", "MyDialog")
          myPO = CreateScriptService("L10N")
          myPO.AddTextsFromDialog(oDlg)
          myPO.ExportToPOTFile("en-US.pot")

##### In Python

          dlg = CreateScriptService("Dialog", "GlobalScope", "Standard", "Dialog1")
          myPO = CreateScriptService("L10N")
          myPO.AddTextsFromDialog(dlg)
          myPO.ExportToPOTFile("en-US.pot")

## ExportToPOTFile

Esporta un insieme di stringhe non tradotte in un file POT.

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.

### Sintassi:

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

### Parametri:

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

### Esempio:

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

Il file generato dovrebbe passare il controllo del comando GNU msgfmt --check senza errori.

## GetText

Gets the translated string corresponding to the given msgid argument.

Potete specificare un elenco di argomenti che sostituisca i segnaposti (%1, %2, ...) nella stringa.

Se non viene trovata nessuna stringa tradotta, il metodo restituisce la stringa non tradotta dopo aver sostituito i segnaposti con gli argomenti specificati.

### Sintassi:

Questo metodo può essere chiamato sia con il suo nome intero GetText o con l'abbreviazione _ (un singolo carattere di sottolineatura):

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.

### Parametri:

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.

### Esempio:

##### In Basic

Considerate che il seguente codice sia in esecuzione in una installazione di LibreOffice con le impostazioni locali "es-ES" (spagnolo-Spagna). In aggiunta, all'interno della cartella specificata è presente un file "es-ES.po" che traduce le stringhe passate al metodo GetText:

          myPO = CreateScriptService("L10N", "C:\myPOFiles\")
          myPO.GetText("Welcome %1! Hope you enjoy this program", "John")
          ' "¡Bienvenido John! Espero que disfrutes de este programa"

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

All ScriptForge Basic routines or identifiers that are prefixed with an underscore character "_" are reserved for internal use. They are not meant be used in Basic macros or Python scripts.

Argomenti correlati

Servizio ScriptForge.FileSystem

Traduzione dei campi di controllo nell'editor delle finestre di dialogo