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.


This service implements the methods listed below:

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

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.

note

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

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

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 method returns True if successful.

note

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

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

note

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:

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

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.