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¬†:

note

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.

tip

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 :

note

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 :

note

‚ÄĘ 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".

note

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

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")
    
Ic√īne Astuce

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

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¬†:

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

note

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

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

note

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¬†:

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

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.


Aidez-nous !