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:

note

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.

tip

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 metodi elencati di seguito:

note

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

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

note

• Basic macros require to load ScriptForge library using the following statement:
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Python scripts require an import from scriptforge module:
from scriptforge import CreateScriptService


There are several ways to invoke the L10N service using up to five optional arguments that specify the folder where PO files are stored, the locale and encoding to be used, as well as a fallback PO file and its encoding.

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: A string specifying the fallback locale to be used in case the PO file corresponding to the locale defined the locale parameter does not exist. This parameter is expressed in the form "la-CO" (language-COUNTRY) or "la" (language) only.

encoding2: The character set of the fallback PO file corresponding to the locale2 argument. The default encoding is "UTF-8".

note

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


Esempio:

In Basic

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


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

The example below specifies the folder containing the PO files. Because the locale is not defined, the service instance will use the locale defined for the LibreOffice user interface, which is the same locale defined in the OfficeLocale property of the Platform service.


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

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


In the example below, the locale is explicitly defined to be Belgian French ("fr-BE"), hence the service will load the file "fr-BE.po" from the folder "C:\myPOFiles". If the file does not exist, an error will occur.


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

To avoid errors, it is possible to specify a preferred and a fallback locale and encoding. The following example will first try to load the file "fr-BE.po" from the specified folder and if it does not exist, the file "en-US.po" will be loaded.


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

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

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 metodo restituisce True, se eseguito correttamente.

note

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

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 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("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')
    
note

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

note

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:

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"
    
warning

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.