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.

Questo servizio implementa i tre metodi elencati di seguito:

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

- 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 As String [, Locale as String]])

FolderName: La cartella che contiene i file PO. Deve essere espressa nella notazione FileSystem.FileNaming.

Locale: Una stringa nel formato "li-PA" (lingua-PAESE) o in formato solo "li" (lingua)

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

Questo servizio è pienamente supportato sia in Basic, sia in Python. Tutti gli esempi sono espressi nel linguaggio di programmazione Basic e possono essere facilmente convertiti in Python.

### Esempio:

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

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

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

## AddText

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

### Sintassi:

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

### Parametri:

Context: La chiave con cui ricercare le stringhe tradotte con il metodo GetText. Questo parametro ha come valore predefinito "".

MsgId: La stringa non tradotta che corrisponde al testo che appare nel codice del programma. Non deve essere vuota. MsgId diventa la chiave con cui trovare la stringa tradotta tramite il metodo GetText se Context è vuoto.

La stringa MsgId può contenere un numero qualunque di segnaposti (%1 %2 %3 ...) per la modifica dinamica della stringa in fase di esecuzione.

Comment: Un commento opzionale da aggiungere accanto alla stringa per aiutare i traduttori.

### Esempio:

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

           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

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

Per creare un insieme di stringhe potete usare una sequenza di chiamate al metodo AddText, oppure invocare correttamente il servizio L10N con l'argomento FolderName presente. È anche possibile usare una combinazione di entrambe le tecniche.

### Sintassi:

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

### Parametri:

FileName: il file di output in notazione FileSystem.FileNaming.

Header: commenti che saranno aggiunti in testa al file POT generato.

Non inserite alcun carattere "#" a inizio riga. Se volete suddividere l'intestazione su più righe inserite delle sequenze di escape (\n) dove richiesto. Un'intestazione standard sarà aggiunta accanto al testo specificato nell'argomento Header.

Encoding: la codifica caratteri da usare (predefinita = "UTF-8").

### Esempio:

             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

Ottiene le stringhe tradotte corrispondenti all'argomento MsgId specificato.

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

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

Nella libreria ScriptForge, tutti i metodi che iniziano col carattere "_" sono riservati al solo uso interno. L'abbreviazione _ usata per GetText tuttavia è l'unica eccezione a questa regola e per tale motivo può essere usata in modo sicuro negli script in Basic.

### Parametri:

MsgId: la stringa non tradotta, che corrisponde al testo che appare nel codice del programma. Non deve essere vuota. Può contenere un numero qualsiasi di segnaposti (%1 %2 %3 ...), utilizzabili per l'inserimento dinamico del testo al tempo di esecuzione (runtime).

Oltre a usare una singola stringa MsgId, questo metodo accetta anche i seguenti formati:

- La stringa Context con cui il metodo trova MsgId nel file PO, oppure;

- Una combinazione Context|MsgId, che ordina al metodo di recuperare MsgId utilizzando il valore specificato di Context. La seconda parte dell'argomento è usata per migliorare la leggibilità del codice.

Arg1, ...: i valori da inserire nei segnaposti. È permesso qualsiasi tipo di variabile, ma saranno prese in considerazione solamente stringhe, numeri e date.

### Esempio:

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

Tutte le routine e gli identificatori Basic di ScriptForge che iniziano con un carattere di sottolineatura "_" sono riservati per uso interno. Non è previsto il loro utilizzo nelle macro in Basic.

Argomenti correlati

Servizio ScriptForge.FileSystem

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