Service ScriptForge.L10N

Ce service fournit un certain nombre de méthodes liées à la traduction des chaînes avec un impact minimal sur le code source du programme. Les méthodes fournies par le service L10N permettent principalement de :

Créer des fichiers POT qui peuvent être utilisés comme modèles pour la traduction de toutes les chaînes du programme.
Obtenir les chaînes traduites au moment de l'exécution pour la langue définie dans la propriété Locale.

L'acronyme L10N signifie Localization et fait référence à un ensemble de procédures de traduction de logiciels vers une langue ou une région spécifique.

Les fichiers PO sont depuis longtemps promus dans la communauté des logiciels libres comme un moyen de fournir des interfaces utilisateur multilingues. Ceci est accompli grâce à l'utilisation de fichiers texte lisibles par l'homme avec une structure bien définie qui spécifie, pour une langue donnée, la chaîne de langue source et la chaîne localisée.

Le principal avantage du format PO est la dissociation du programmeur et du traducteur. Les fichiers PO sont des fichiers texte indépendants, de sorte que le programmeur peut envoyer des fichiers modèles POT aux traducteurs, qui traduiront ensuite leur contenu et renverront les fichiers PO traduits pour chaque langue prise en charge.

Le service L10N est basé sur l'implémentation GNU des fichiers PO (portable object). Pour en savoir plus sur ce format de fichier, visitez GNU gettext Utilities : PO Files.

Ce service implémente les méthodes listées ci-dessous :

AddText : utilisé par le programmeur pour construire un ensemble de chaînes qui seront traduites ultérieurement.
AddTextsFromDialog : extrait toutes les chaînes d'une instance de service Dialog.
ExportToPOTFile : exporte les chaînes ajoutées par la méthode AddText vers un fichier POT.
GetText : obtient les chaînes traduites au moment de l'exécution.

Notez que les deux premières méthodes sont utilisées pour créer un ensemble de chaînes traduisibles et les exporter vers un fichier POT. Cependant, il n'est pas obligatoire de créer des fichiers POT à l'aide de ces méthodes. Puisqu'il s'agit de fichiers texte, le programmeur aurait pu les créer à l'aide de n'importe quel éditeur de texte.

Invocation du service

Avant d'utiliser le service L10N, la bibliothèque ScriptForge doit être chargée ou importée :

• Les macros Basic nécessitent de charger la bibliothèque ScriptForge à l'aide de l'instruction suivante :
GlobalScope.BasicLibraries.loadLibrary("ScriptForge")

• Les scripts Python nécessitent un import depuis le module scriptforge :
from scriptforge import CreateScriptService

Il existe plusieurs façons d'invoquer le service L10N en utilisant jusqu'à cinq arguments facultatifs qui spécifient le dossier dans lequel les fichiers PO sont stockés, les paramètres régionaux et l'encodage à utiliser, ainsi qu'un fichier PO de secours et son encodage .

Syntaxe :

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

foldername : le dossier contenant les fichiers PO. Il doit être exprimé dans la notation FileSystem.FileNaming.

locale : une chaîne sous la forme "la-CO" (langue-PAYS) ou sous la forme "la" (langue) uniquement.

encoding : le jeu de caractères à utiliser. L'encodage par défaut est "UTF-8".

locale2 : une chaîne spécifiant la locale de secours à utiliser au cas où le fichier PO correspondant à la locale définie par le paramètre locale n'existe pas. Ce paramètre est exprimé sous la forme "la-CO" (langue-PAYS) ou "la" (langue) uniquement.

encoding2 : jeu de caractères du fichier PO de secours correspondant à l'argument locale2. L'encodage par défaut est "UTF-8".

Pour en savoir plus sur les noms des jeux de caractères, visitez la page Jeu de caractères de l'IANA. N'oubliez pas que LibreOffice n'implémente pas tous les jeux de caractères existants.

Exemple :

En Basic :

L'exemple suivant instancie le service L10N sans aucun argument facultatif. Cela n'activera que les méthodes AddText et ExportToPOTFile, ce qui est utile pour créer des fichiers POT.


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

L'exemple ci-dessous spécifie le dossier contenant les fichiers PO. Étant donné que les paramètres régionaux ne sont pas définis, l'instance de service utilisera les paramètres régionaux définis pour l'interface utilisateur LibreOffice, qui sont les mêmes que ceux définis dans la propriété OfficeLocale du service Platform.


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

L'exemple ci-dessus entraînera une erreur d'exécution si le fichier PO correspondant à la locale OfficeLocale n'existe pas dans le dossier spécifié.

Dans l'exemple ci-dessous, la locale est explicitement définie comme étant le français belge ("fr-BE"), par conséquent le service chargera le fichier "fr-BE.po" à partir du dossier "C:\myPOFiles". Si le fichier n'existe pas, une erreur se produira.


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

Pour éviter les erreurs, il est possible de spécifier une locale et un encodage préférés et de secours. L'exemple suivant essaiera d'abord de charger le fichier "fr-BE.po" depuis le dossier spécifié et s'il n'existe pas, le fichier "en-US.po" sera chargé.


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

Les fichiers PO doivent être nommés sous la forme "la-CO.po" ou "la.po", où "la" fait référence à la langue et "CO" au pays. Quelques exemples sont : "en-US.po", "fr-BE.po" ou "fr.po".

Il est recommandé de libérer des ressources après utilisation :


      Set myPO = myPO.Dispose()

En Python

Les exemples ci-dessus peuvent être traduits en Python comme suit :


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

Plusieurs instances du service L10N peuvent coexister. Cependant, chaque instance doit utiliser un répertoire distinct pour ses fichiers PO.

Propriétés

Nom	Lecture seule	Type	Description
Folder	Oui	String	Le dossier contenant les fichiers PO (voir la propriété FileSystem.FileNaming pour en savoir plus sur la notation utilisée).
Languages	Oui	Array	Une matrice de base zéro listant tous les noms de base (sans l'extension ".po") des fichiers PO trouvés dans le Folder spécifié.
Locale	Oui	String	La combinaison langue-PAYS actuellement active. Cette propriété sera initialement vide si le service a été instancié sans aucun des arguments facultatifs.

Liste des méthodes dans le service L10N
AddText AddTextsFromDialog	ExportToPOTFile	GetText

AddText

Ajoute une nouvelle entrée dans la liste des chaînes localisables. elle ne doit pas encore exister.

La méthode renvoie True en cas de succès.

Syntaxe :

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

Paramètres :

context : la clé pour récupérer la chaîne traduite avec la méthode GetText. Ce paramètre a une valeur par défaut de "".

msgid : la chaîne non traduite, qui est le texte apparaissant dans le code du programme. Elle ne doit pas être vide. Le msgid devient la clé pour récupérer la chaîne traduite via la méthode GetText lorsque context est vide.

La chaîne msgid peut contenir n'importe quel nombre d'espaces réservés (%1 %2 %3 ...) pour modifier dynamiquement la chaîne lors de l'exécution.

comment : commentaire facultatif à ajouter à côté de la chaîne pour aider les traducteurs.

Exemple :

L'exemple ci-dessous crée un ensemble de chaînes en anglais :

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

En 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

Extrait automatiquement les chaînes d'une boîte de dialogue et les ajoute à la liste des chaînes de texte localisables. Les chaînes suivantes sont extraites :

Le titre de la boîte de dialogue.
La légende des types de contrôle suivants : Button, CheckBox, FixedLine, FixedText, GroupBox et RadioButton.
Chaînes statiques dans les ListBoxes et les ComboBoxes.
Info-bulle ou texte d'aide affiché lorsque la souris survole le contrôle.

La méthode renvoie True en cas de succès.

La boîte de dialogue à partir de laquelle les chaînes seront extraites ne doit pas être ouverte lorsque la méthode est appelée.

Lorsqu'une instance de service L10N est créée à partir d'un fichier PO existant, utilisez la méthode GetTextsFromL10N du service Dialog pour charger automatiquement toutes les chaînes traduites dans la boîte de dialogue.

Syntaxe :

svc.AddTextsFromDialog(dialog: svc): bool

Paramètres :

dialog : une instance de service Dialog correspondant à la boîte de dialogue dont les chaînes seront extraites.

Exemple :

L'exemple suivant extrait toutes les chaînes de la boîte de dialogue "MyDialog" stockées dans la bibliothèque "Standard" et les exporte vers un fichier POT :

En Basic :


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

En Python


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

ExportToPOTFile

Exporte un ensemble de chaînes non traduites en tant que fichier POT.

Pour construire un ensemble de chaînes, vous pouvez utiliser soit une succession d'appels de la méthode AddText, soit une invocation réussie du service L10N avec l'argument foldername présent. Il est également possible d'utiliser une combinaison des deux techniques.

La méthode renvoie True en cas de succès.

Syntaxe :

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

Paramètres :

filename : le nom complet du fichier de sortie en notation FileSystem.FileNaming.

header : commentaires qui seront ajoutés en haut du fichier POT généré.

N'incluez aucun caractère "#" en tête. Si vous souhaitez que l'en-tête soit divisé en plusieurs lignes, insérez des séquences d'échappement (\n) le cas échéant. Un en-tête standard sera ajouté à côté du texte spécifié dans l'argument header.

encoding : le jeu de caractères à utiliser (par défaut = "UTF-8").

Exemple :


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

Le fichier généré doit réussir la commande GNU msgfmt --check.

GetText

Obtient la chaîne traduite correspondant à l'argument msgid donné.

Une liste d'arguments peut être spécifiée pour remplacer les espaces réservés (%1, %2, ...) dans la chaîne.

Si aucune chaîne traduite n'est trouvée, la méthode renvoie la chaîne non traduite après avoir remplacé les espaces réservés par les arguments spécifiés.

Syntaxe :

Cette méthode peut être appelée soit par le nom complet GetText soit par le raccourci _ (un seul trait de soulignement) :

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

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

Dans la bibliothèque ScriptForge, toutes les méthodes commençant par le caractère "_" sont réservées à un usage interne uniquement. Cependant, le raccourci _ utilisé pour GetText est la seule exception à cette règle, il peut donc être utilisé en toute sécurité dans les scripts Basic et Python.

Paramètres :

msgid : la chaîne non traduite, qui est le texte apparaissant dans le code du programme. Elle ne doit pas être vide. Elle peut contenir n'importe quel nombre d'espaces réservés (%1 %2 %3 ...) qui peuvent être utilisés pour insérer dynamiquement du texte lors de l'exécution.

Outre l'utilisation d'une seule chaîne msgid, cette méthode accepte également les formats suivants :

La chaîne context avec laquelle la méthode récupérera le msgid dans le fichier PO, ou ;
Une combinaison context|msgid, demandant à la méthode de récupérer le msgid en utilisant la valeur context spécifiée. La deuxième partie de l'argument est utilisée pour améliorer la lisibilité du code.

args : valeurs à insérer dans les espaces réservés. Tout type de variable est autorisé, mais seuls les chaînes, les nombres et les dates seront pris en compte.

Exemple :

En Basic :

Considérez que le code suivant s'exécute sur une installation LibreOffice avec les paramètres régionaux définis sur "es-ES". De plus, il existe un fichier "es-ES.po" dans le dossier spécifié qui traduit la chaîne transmise à la méthode GetText :


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

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

Toutes les routines ou identifiants de base ScriptForge qui sont préfixés par un caractère de soulignement "_" sont réservés à un usage interne. Ils ne sont pas destinés à être utilisés dans des macros de base ou des scripts Python.

ScriptForge. Service FileSystem

Traduction des contrôles dans l'éditeur de boîte de dialogue