Aide:Extension:Traduire/Exemple de configuration de groupe

From mediawiki.org
This page is a translated version of the page Help:Extension:Translate/Group configuration example and the translation is 100% complete.

Ce guide est destiné aux développeurs et aux administrateurs de traduction expérimentés. Il explique comment créer de nouveaux fichiers de configuration pour les traductions des messages de l'interface du logiciel, en détaillant ses principaux aspects. Ce guide est à utiliser en parallèle du manuel de référence de la configuration de groupes et les développeurs de l'extension Translate vous aideront volontiers si vous avez la moindre question après avoir travaillé avec ce guide.

Pré-requis

Ce tutoriel a été créé en se basant sur la version r97948 de l'extension Translate (en date du 23/09/2011).

Ce tutoriel décrit le processus d'activation de la traduction pour certaines parties du projet MyBB. Vous pouvez suivre des étapes similaires afin d'ajouter d'autres projets ou fichiers à traduire. Quelques éléments sont spécifiques à translatewiki.net et vous devriez naturellement utiliser ce qui est pertinent dans votre cas, sans suivre aveuglément les étapes de ce tutoriel.

Étape 1 : vérifier notre code source

Récupérons le code source de MyBB avec $wgTranslateGroupRoot comme répertoire de travail, représenté par /home/betawiki/projects/ dans cet exemple.

cd /home/betawiki/projects svn co http://svn.mybboard.net/mybb/branches/1.6-stable mybb

Selon votre configuration, vous pourrez avoir besoin d'exécuter ceci en tant que root ou en tant qu'un autre utilisateur avant d'ajouter des fichiers de projets ou de configuration. Sur translatewiki.net, l'utilisateur est "betawiki", ainsi, la commande ci-dessus sera en réalité exécutée comme ceci :

sudo -u betawiki svn co http://svn.mybboard.net/mybb/branches/1.6-stable mybb

Maintenant, il nous faut trouver les fichiers contenant les messages. Ils se trouvent dans le sous-dossier mybb/inc/languages/, et vous pouvez y trouver les messages source en anglais dans le sous-dossier english/.

Commençons donc avec mybb/inc/languages/english/index.lang.php, le premier fichier de localisation de notre projet.

Étape 2 : Gestion du format de fichier

Dans notre dossier d'installation de MediaWiki, dans FFS.php et Translate/ffs/ [1], nous pouvons voir les classes gérant le format de fichier, qui sont utilisées pour faire correspondre les groupes de messages aux fichiers de localisation de chaque projet. Vous devez fouiller un peu pour bien voir les types de formats qui sont gérés. Allons donc faire un essai et utiliser pour commencer la classe FlatPhpFFS afin de voir comment elle fonctionne avec notre fichier PHP.

Nous avons donc un fichier à faire correspondre et nous avons choisi la classe FFS pour cela. Nous avons maintenant besoin d'écrire une configuration de groupe. Il s'agit d'un fichier YAML.

Dans l'index , vous pourrez trouver un lien vers le fichier de configuration de groupe . Commençons avec un fichier minimal, fourni à titre d'exemple pour la section BASIC.

BASIC:
  id: out-freecol
  label: FreeCol (open source game)
  description: "{{int:bw-desc-freecol}}"
  namespace: NS_FREECOL
  class: FileBasedMessageGroup

Nous pouvons y aller et simplement remplacer le texte d'exemple par nos propres valeurs.

BASIC:
  id: out-mybb
  label: MyBB
  description: "[[Translating:MyBB|MyBB]] is a web-based discussion forum software"
  namespace: NS_MYBB
  class: FileBasedMessageGroup

La description accepte toute syntaxe en wikitexte. Une astuce pratique montrée dans l'exemple original consiste à le rendre traduisible avec {{int:message-key}}. Mais vous devez alors définir le texte par défaut sur la page [[MediaWiki:Message-key]]. Notez que l'identifiant de l'espace de noms est ajouté via sa constante, voir comment utiliser des espaces de noms personnalisés.

Nous avons besoin d'une dernière chose : la section FILES. En partant toujours de l'exemple fourni dans la documentation :

FILES:
  class: FlatPhpFFS
  sourcePattern: %GROUPROOT%/inc/languages/messages_%CODE%.properties
  targetPattern: commonist/messages_%CODE%.properties

Hum, %CODE% est le code de la langue, qui vaut en par défaut. Pour l'instant, nous ne voulons pas modifier la structure des dossiers utilisée par MyBB. Au lieu de cela, nous pouvons utiliser une fonctionnalité conçue à cet effet : la correspondance de code (code map), qui nous permet de faire correspondre le code de chaque langue avec les identifiants utilisés dans notre projet.

Et nous obtenons :

FILES:
  class: FlatPhpFFS
  sourcePattern: %GROUPROOT%/mybb/inc/languages/%CODE%/index.lang.php
  targetPattern: mybb/inc/languages/%CODE%/index.lang.php
  codeMap:
    en: english
    "no": norwegian
Attention, vous aurez besoin des guillemets de part et d'autre du code de langue no, car certains analyseurs syntaxiques de YAML peuvent sinon l'interpréter cela comme un booléen.

En gros cela dit que pour le code en, l'élément %CODE% au dessus vaudra english, ce qui correspond au dossier des fichiers des messages en anglais. La clé targetPattern contient en général la même valeur que sourcePattern, mais sans le préfixe %GROUPROOT%.

Bien. Enregistrons maintenant ce fichier quelque part, par exemple dans le même dossier que LocalSettings.php , en le nommant MyBB.yaml. Le fichier complet contient ceci :

BASIC:
  id: out-mybb
  label: MyBB
  description: "[[Translating:MyBB|MyBB]] is a web-based discussion forum software"
  namespace: NS_MYBB
  class: FileBasedMessageGroup

FILES:
  class: FlatPhpFFS
  sourcePattern: %GROUPROOT%/mybb/inc/languages/%CODE%/index.lang.php
  targetPattern: mybb/inc/languages/%CODE%/index.lang.php
  codeMap:
    en: english
    "no": norwegian

Nous devons alors dire à notre extension de lire ce fichier. Ajoutez la ligne suivante dans le fichier LocalSettings.php :

$wgTranslateGroupFiles[] = "MyBB.yaml";

Après cela, suivez les instructions de la page Help:Extension:Translate/Gestion de groupe pour exécuter le script processMessageChanges.php.

Connectons-nous, en s'assurant que l'utilisateur dispose du droit translate-manage correctement configuré, et allons sur [[Special:ManageMessageGroups]].

Vous devriez obtenir ceci :

No valid namespace defined, got NS_MYBB.
Backtrace: <...>

Dans ce cas, en lisant attentivement la documentation, vous pourriez avoir noté qu'il est nécessaire d'ajouter la ligne suivante au fichier LocalSettings.php pour enregistrer le nouvel espace de noms dans MediaWiki :

wfAddNamespace( 1246, 'MyBB' );

Dans cet exemple, la valeur 1246 est utilisée, mais vous pouvez choisir n'importe quel autre numéro disponible d'espace de noms. Pour l'extension Translate, nous vous recommandons d'utiliser des numéros d'espaces de noms pairs situés dans l'intervalle 1200-1298.

Si vous rechargez maintenant la page spéciale ManageMessageGroups, vous devriez voir une ligne mentionnant :

MyBB This message group has not been imported previously.

Cliquez sur le lien MyBB. Après cela, vous allez voir la liste des messages qui se trouvent dans ce fichier. Si les résultats vous conviennent, cliquez sur "Exécuter".

Après avoir cliqué sur "Execute", le fichier est traité et vous verrez des résultats s'afficher, qui devraient ressembler à ceci :

Imported new version of page MyBB:L\x5b'boardstats'\x5d/en.
Imported new version of page MyBB:L\x5b'new posts'\x5d/en.
Imported new version of page MyBB:L\x5b'no new posts'\x5d/en.
...
Cache rebuild.
All done!

Si le fichier est très gros, vous aurez besoin d'exécuter d'abord php Translate/scripts/sync-group.php --group=out-mybb --lang=en, car l'interface web ne peut importer qu'un nombre limité de messages en une fois, en raison d'une limitation sur le temps d'exécution du code PHP (le timeout) ; si vous butez sur cette limite, vous pouvez cliquer sur un bouton en bas de la page pour importer les messages restants.

Étape 3 : Ajouter un autre fichier

Maintenant, ajoutons un second fichier de traduction pour MyBB. Il y a deux manières de le faire :

Approche 1 : ajouter un nouveau fichier YAML

Ajoutez simplement un nouveau fichier YAML et enregistrez-le sous un nouveau nom. Appelez-le ensuite depuis le fichier LocalSettings.php et suivez toutes les étapes ci-dessus. Le fichier ressemblera à quelque chose comme :

BASIC:
  id: out-mybb-showthread
  label: MyBB
  description: "[[Translating:MyBB|MyBB]] is a web-based discussion forum software"
  namespace: NS_MYBB
  class: FileBasedMessageGroup

FILES:
  class: FlatPhpFFS
  sourcePattern: %GROUPROOT%/mybb/inc/languages/%CODE%/showthread.lang.php
  targetPattern: mybb/inc/languages/%CODE%/showthread.lang.php
  codeMap:
    en: english
    "no": norwegian

Évidemment, comme c'est indiqué dans l'exemple ci-dessus, vous devrez utiliser un identifiant différent pour ce nouveau groupe.

Bien que simple, cette approche ne convient pas pour des centaines d'unités de traduction (c'est-à-dire des fichiers mis en correspondance avec leurs groupes de messages). Il arrive un moment où vous avez besoin de mettre à jour un valeur, et le faire pour tous ces fichiers n'a rien d'amusant. Heureusement, il existe une autre méthode, décrite plus bas.

Approche 2 : syntaxe TEMPLATE

L'idée consiste à rassembler les valeurs communes dans un patron. Ainsi, chaque groupe va prendre les valeurs manquantes dans le patron, et il n'y aura pas besoin de les répéter pour chaque groupe.

Revenons à l'exemple du MyBB. Disons par exemple que vous voulez intégrer les fichiers index.lang.php, showthread.lang.php et global.lang.php dans les messages pouvant être traduit. Le fichier YAML doit être mis à jour comme ceci :

TEMPLATE:
  BASIC:
    description: "[[Translating:MyBB|MyBB]] is a web-based discussion forum software"
    namespace: NS_MYBB
    class: FileBasedMessageGroup

  FILES:
    class: FlatPhpFFS
    codeMap:
      en: english
      "no": norwegian
---
BASIC:
  id: out-mybb-index
  label: MyBB - index page

FILES:
  sourcePattern: %GROUPROOT%/mybb/inc/languages/%CODE%/index.lang.php
  targetPattern: mybb/inc/languages/%CODE%/index.lang.php
---
BASIC:
  id: out-mybb-showthread
  label: MyBB - show thread

FILES:
  sourcePattern: %GROUPROOT%/mybb/inc/languages/%CODE%/showthread.lang.php
  targetPattern: mybb/inc/languages/%CODE%/showthread.lang.php
---
BASIC:
  id: out-mybb-global
  label: MyBB - global messages

FILES:
  sourcePattern: %GROUPROOT%/mybb/inc/languages/%CODE%/global.lang.php
  targetPattern: mybb/inc/languages/%CODE%/global.lang.php
Remarquez que chaque groupe doit être séparé des autres par une ligne contenant trois tirets ---, sans espaces au début ni à la fin ! Dans le cas contraire, le fichier YAML ne sera pas correctement analysé.

De manière évidente dans l'exemple précédent, codeMap n'est défini qu'une seule fois ; l'ajout et la suppression de fichiers est aussi simple que l'ajout ou le retrait de sections dans le fichier ci-dessus.

Maintenant, si vous allez sur la page spéciale ManageMessageGroups, vous y verrez trois éléments comme ceci :

MyBB global messages: This message group has not been imported previously.
MyBB index page: This message group has not been imported previously.
MyBB show thread: This message group has not been imported previously.

S'il y a de nombreux fichiers à intégrer dans votre projet, il peut être judicieux d'écrire un programme qui va générer votre fichier YAML à votre place. Un exemple peut être consulté sur la page svn:trunk/translatewiki/StatusNet/genStatusNet-plugins.php.

Étape 4 : Groupe agrégé

L'ajout d'un groupe agrégé et la définition des fichiers de messages comme sous-groupes du groupe agrégé comportent deux avantages :

  • Cela fait moins de travail pour les traducteurs lorsqu'ils choisissent les différents groupes de messages, en particulier lors des tâches de maintenance. Les traducteurs peuvent simplement ouvrir les groupes agrégés et traduire ou mettre à jour tout ce qui a besoin d'être traduit ou d'être mis à jour pour l'ensemble des groupes.
  • Des statistiques peuvent être calculées au niveau du groupe agrégé, c'est-à-dire au niveau du projet entier.

Afin de définir un groupe agrégé, vous devez ajouter la section suivante juste après la section TEMPLATE et avant la définition des sous-groupes individuels :

---
BASIC:
  id: out-mybb-0-all # The id should sort before all the subgroups it has
  label: MyBB
  meta: yes
  class: AggregateMessageGroup # Not taken from template

GROUPS:
  - out-mybb-* # We could specify them one by one, but wildcard is easier

Nous y sommes presque, mais il reste une dernière étape. À ce stade, si vous allez sur Special:Translate, vous verrez le groupe parent de MyBB (et cela marche vraiment !) mais aussi les sous-groupes, qui sont aussi listés en tant que groupes distincts. :(

Voici la manière de corriger cela. Ajoutez la ligne suivante à votre fichier LocalSettings.php :

$wgTranslateGroupStructure['/^out-mybb/'] = array( 'mybb' );
Un groupe agrégé sous sa forme dépliée (le voir en mode replié)

Ceci prend tous les groupes dont l'identifiant correspond au modèle donné, montre le premier groupe, et cache tous les éléments restants se trouvant sous ce premier groupe. Ce n'est pas très propre, mais cela fonctionne. Cette construction ne permet de gérer que deux niveaux, même si un groupe agrégé peuvent faire partie d'un autre groupe agrégé.

Si vous allez maintenant sur [[Special:Translate]], vous ne verrez que le groupe parent de MyBB dans la liste. De plus, vous verrez un lien "Montrer 3 sous-groupes" ; en cliquant dessus, vous obtiendrez les noms des sous-groupes.

Consultez le manuel à propos des TAGS et d'autres notions que ce document ne couvre pas.

Étape 5 : Nettoyage

Les fichiers YAML des projets gérés par translatewiki.net sont sauvegardés sur le dépôt translatewiki avec Git.

Sur translatewiki.net, le contenu du fichier LocalSettings.php se trouve en fait dans le fichier TranslateSettings.php. Sandboxwiki, sur translatewiki.net, ne dispose pas d'un fichier TranslateSettings.php, et c'est pourquoi nous avons tout placé dans le fichier LocalSettings.php.