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, visitare GNU gettext Utilities: PO Files.

Questo servizio implementa i metodi elencati di seguito:

AddText: Usato dal programmatore per costruire un insieme di stringhe che saranno tradotte in seguito.
AddTextsFromDialog: estrae tutte le stringhe da un'istanza del servizio Dialog.
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.

Invocazione del servizio

Prima di usare il servizio L10N è necessario caricare o importare le librerie ScriptForge:

• Le macro in Basic richiedono il caricamento della libreria ScriptForge usando la seguente istruzione:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Gli script in Python richiedono un'importazione dal modulo scriptforge:
from scriptforge import CreateScriptService

Ci sono diversi modi per invocare il servizio L10N usando un massimo di cinque argomenti facoltativi che specificano la cartella in cui sono memorizzati i file PO, la lingua locale e la codifica da usare, così come un file PO di ripiego e la sua codifica.

Sintassi:

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

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)

encoding: la codifica caratteri da usare. La codifica predefinita è "UTF-8".

locale2: una stringa che specifica la lingua locale di ripiego da usare nel caso in cui il file PO corrispondente a quella definita nel parametro locale non esista. Questo parametro è espresso nel formato "li-PA" (lingua-PAESE) o solo "li" (lingua).

encoding2: la codifica caratteri del file PO di ripiego corrispondente all'argomento locale2. La codifica predefinita è "UTF-8".

Per saperne di più in merito ai nomi delle codifiche dei caratteri, visitate la pagina Codifiche dei caratteri IANA. È bene notare che LibreOffice non implementa tutte le codifiche dei caratteri esistenti.

Esempio:

In Basic

L'esempio seguente istanzia il servizio L10N senza alcun argomento opzionale. Questo attiverà solo i metodi AddText e ExportToPOTFile, utili per la creazione di file POT.


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

L'esempio sottostante specifica la cartella contenente i file PO. Dato che la lingua locale non è definita, l'istanza del servizio userà quella definita per l'interfaccia utente di LibreOffice, che è la stessa lingua locale definita nella proprietà OfficeLocale del servizio Platform.


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

L'esempio qui sopra genera un errore in fase di esecuzione se il file PO corrispondente alla lingua locale OfficeLocale non esiste nella cartella specificata.

Nell'esempio sottostante, la lingua locale è definita esplicitamente come francese del Belgio ("fr-BE"), quindi il servizio caricherà il file "fr-BE.po" dalla cartella "C:\myPOFiles". Se il file non esiste, si verificherà un errore.


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

Per evitare errori, è possibile precisare una lingua locale preferita, una di ripiego e la loro codifica. L'esempio seguente prova prima a caricare il file "fr-BE.po" dalla cartella specificata e se non esiste, caricherà il file "en-US.po".


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

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

Gli esempi qui sopra possono essere portati in Python come segue:


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

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

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

Il metodo restituisce True, se eseguito correttamente.

Sintassi:

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

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:

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

Estrae automaticamente le stringhe da una finestra di dialogo e le aggiunge all'elenco delle stringhe di testo localizzabili. Vengono estratte le seguenti stringhe:

Il titolo della finestra di dialogo.
Le etichette dei seguenti tipi di campo di controllo: Pulsanti, Caselle di controllo, Linee fisse, Testi fissi, Caselle di riepilogo e Pulsanti di scelta.
Stringhe statiche delle Caselle di riepilogo e delle Caselle combinate.
I suggerimenti e gli aiuti testuali visualizzati quando il puntatore del mouse si sofferma sul controllo.

Il metodo restituisce True, se eseguito correttamente.

Quando il metodo viene richiamato, la finestra di dialogo da cui saranno estratte le stringhe deve risultare chiusa.

Quando create l'istanza del servizio L10N da un file PO esistente, usate il metodo GetTextsFromL10N del servizio Dialog per caricare automaticamente tutte le stringhe tradotte nella finestra di dialogo.

Sintassi:

svc.AddTextsFromDialog(dialog: svc): bool

Parametri:

dialog: un'istanza del servizio Dialog che corrisponde alla finestra di dialogo da cui estrarre le stringhe.

Esempio:

L'esempio seguente estrae tutte le stringhe dalla finestra di dialogo "MyDialog" memorizzata nella libreria "Standard" e le esporta in un file POT:

In Basic


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

In Python


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

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.

Il metodo restituisce True, se eseguito correttamente.

Sintassi:

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

Parametri:

filename: il nome completo del file di output in notazione FileSystem.FileNaming.

header: commenti che saranno aggiunti in cima 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: il set di caratteri da usare (predefinito = "UTF-8").

Esempio:


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

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

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

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

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 e in Python.

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 in fase 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 di context specificato. La seconda parte dell'argomento è usata per migliorare la leggibilità del codice.

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

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"

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 o negli script in Python.

Servizio ScriptForge.FileSystem

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