Help:Messages système

From mediawiki.org
This page is a translated version of the page Help:System message and the translation is 99% complete.
PD Note : si vous modifiez cette page, vous acceptez de placer votre contribution sous licence CC0. Plus d’informations sont disponibles sur les pages d’aide concernant le domaine public.
PD
documents i18n
Capture d'écran commentée de l'interface « Téléverser un fichier », montrant les différents messages système.

Un message système est un fragment de texte brut, de wikitexte, de CSS ou de JavaScript, qui peut être utilisé pour personnaliser le comportement de MediaWiki et son apparence pour chaque langue et paramètres régionaux. MediaWiki utilise des messages pour chaque partie de l'interface visible par l'utilisateur, permettant l'internationalisation et la régionalisation de l'interface utilisateur de MediaWiki, tant pour son cœur que pour ses extensions. Tous les messages utilisés dans MediaWiki sont définis dans un fichier de messages.

Redéfinir les messages sur un wiki

La valeur par défaut des messages peut être modifiée en l'éditant sur chaque wiki. Chaque message possède sa page wiki dans l'espace de noms MediaWiki avec sa clé de message pour nom de page. Par exemple, le message aboutsite est enregistré dans MediaWiki:aboutsite. Par défaut, cet espace de noms est protégé contre toute modification à moins que l'utilisateur n'ait les droits de modificateur d'interface. Une liste de tous les messages se trouve sur Special:AllMessages. Modifier les messages d'interface est très simple et se fait comme pour toute modification de page classique du wiki, mais cela reste réservé aux utilisateurs ayant les droits de modificateur d'interface, c'est à dire par défaut aux administrateurs (et aux administrateurs d'interfaces).

Exemple de ligne de l'ancien Special:AllMessages.

Le tableau de Special:AllMessages contient deux colonnes : le nom du fichier du message système avec un lien pour le consulter, et le texte du message système. Le texte est séparé horizontalement pour montrer le texte par défaut au-dessus, et le texte personnalisé en-dessous. Quand un message personnalisé n'existe pas, seul le texte par défaut apparait. Pour personnaliser un message, cliquez sur le lien supérieur de la colonne de gauche (le nom du message). Le lien est en rouge si le texte par défaut est utilisé, car la page à modifier est vide.

Les liens inférieurs des cellules de la colonne de gauche pointent vers les pages de discussion relatives aux messages.

Trouver les messages et leur documentation

La façon dont chaque message est utilisé par MediaWiki, les variables disponibles, les paramètres utilisés, les limitations, etc. est exposée dans les fichiers de la documentation complète en pseudo-langage qqq, suivant les recomendations pour la documentation des messages. Des pages d'explication plus longues peuvent exister pour quelques messages d'interface dans la plus ancienne Catégorie:messages d'interface .

Dans le wiki utilisé par translatewiki.net, 'qqq' représente la page qui contient la documentation utilisateur du message (en anglais, car c'est le même texte qui est affiché pour tous les lecteurs).

De la même manière que /en /ge /fr ... /qqq est une sous-page de l'article et peut être affichée directement.

De ce point de vue, qqq est considéré comme un langage dans le paramètre language= de la requête.

Dans MediaWiki 1.18 et supérieur, vous pouvez trouver la clé d'un message en consultant un wiki dans en pseudo-langage de code qqx, ce qui peut se faire en ajoutant ?uselang=qqx à l'URL, ou &uselang=qqx si l'URL contient déjà un caractère ? (exemple). Tous les messages seront ensuite remplacés par leur clé de message, de façon à ce que vous puissiez identifier quel message est concerné. Les messages qui sont toujours dans la langue du contenu ne seront pas affichés en utilisant qqx.

Quelques parties de l'interface ajoutent nstab- à la chaîne affichée quand vous utilisez l'astuce qqx. Par exemple l'étiquette de l'onglet qui pointe sur la page de discussion dans l'espace de noms principal est affichée en tant que nstab-talk, mais la chaîne se trouve actuellement dans MediaWiki:Talk.

Dans le cas où la page utilise des onglets comme par exemple la page spéciale "Preferences" vous devrez ajouter l'onglet après le paramètre uselang, par exemple Special:Preferences?uselang=qqx#mw-prefsection-rendering.

Format des fichiers de localisation

Tous les messages utilisés dans MediaWiki sont définis dans un fichier de messages.

Il y a deux types de fichiers de messages dans MediaWiki : JSON et PHP. Depuis avril 2014, le noyau de MediaWiki et la plupart des extensions les mieux maintenues ont migré au format JSON. Vous devez utiliser JSON pour tous les nouveaux développements. Pour plus d'information sur la migration en JSON, voir Requests for comment/Localisation format.

JSON

Depuis la fin 2013 un nouveau format de fichier de messages a été introduit : JSON. C'est le JSON à plat, familier en tant que format commun générique de stockage des données. Chacune des clés est une clé de message, et la valeur est le texte du message. En plus, la clé spéciale @metadata est utilisée pour stocker les informations concernant la traduction telles que les auteurs de la traduction.

L'utilisation de JSON rend les fichiers de localisation plus sécurisés car ce n'est pas du code exécutable. Il est également compatible avec jquery.i18n, une bibliothèque JavaScript développée pour le projet Milkshake, qui fournit des possibilités de traduction de l'interface utilisateur comme celles de MediaWiki et qui est utilisée par certaines extensions qui se veulent plus indépendantes de MediaWiki, telles que VisualEditor ou UniversalLanguageSelector.

Parce que la plus grande suite d'outils d'internationalisation et de localisation était appelée « Project Milkshake » , certaines personnes ont appelé ce format « banane » .

Emplacement des fichiers

Dans le noyau MediaWiki, les fichiers internationalisés se trouvent dans le répertoire languages/i18n . Les extensions MediaWiki mettent habituellement les leurs dans un sous-répertoire i18n/ . Si un projet comporte trop de messages, il est possible de les grouper en deux ou plusieurs sous-répertoires de sujets afin d'en facilter la maintenance. Dans le contexte de MediaWiki, la clé de configuration $wgMessagesDirs est utilisée pour lister ces sous-répertoires. Voici un exemple de l'extension VisualEditor pour MediaWiki :

{
  "MessagesDirs": {
    "VisualEditor": [
      "lib/ve/modules/ve/i18n",
      "modules/ve-mw/i18n",
      "modules/ve-wmf/i18n",
      "lib/ve/lib/oojs-ui/i18n"
    ]
  }
}

Ajoutez les nouveaux messages dans le fichier « en » des messages en anglais « en.json » et documentez-les dans le fichier de documentation des messages ayant comme code spécial de langue « qqq » – qqq.json. Voir aussi : Ajouter de nouveaux messages.

Métadonnées

Actuellement, les champs suivants sont utilisés dans les fichiers pour les métadonnées :

authors
Liste JSON des auteurs des messages. Pour les messages en anglais (en) ainsi que pour la documentation (qqq) ils sont ajoutés manuellement lorsque le fichier des messages est modifié. Pour toutes les autres langues l'insertion est automatique lorsque le fichier des messages est exporté de translatewiki.net. La documentation des messages peut être mise à jour sur translatewiki.net, et les éditeurs de la documentation sont également insérés dans le fichier qqq.json automatiquement.
message-documentation
Ceci est le code du pseudo-langage pour enregistrer la documentation du message. Pour MediaWiki, c'est toujours qqq. (On voit cela dans quelques extensions, mais il n'est pas traité actuellement d'une quelconque manière. Cela n'est pas obligatoire).

Conventions

Les caractères spéciaux tels que les passages à la ligne doivent être échappés ("\n").

Les caractères Unicode qui représentent des lettres dans les différents alphabets sont rangés comme des caractères réels et non pas comme des codes de caractères, car ces fichiers sont quelques fois lus par des personnes et parce que cela produit des fichiers plus petits ("誼" et non pas "\u8ABC"). De façon générale, les développeurs ne modifient que les messages en anglais (rarement dans les autres langues) car ceux-ci sont habituellement traduits en utilisant par translatewiki.net.

Le code HTML n'est pas échappé lui non plus; donc "<strong>Warning</strong>" et non pas "\u003cstrong\u003eWarning\u003c/strong\u003e".

L'indentation dans les fichiers JSON se fait en utilisant les caractères de tabulation.

PHP

L'ancien format du fichier de localisation est PHP. Il s'agit essentiellement d'un tableau PHP contenant tous les messages. Dans le noyau de MediaWiki chaque langue est rangée dans son propre fichier du répertoire languages/message du code source de MediaWiki. Dans les extensions toutes les langues et la documentation des message (qqq) sont dans le même fichier : ExtensionName.i18n.php, habituellement dans le répertoire principal de l'extension.

Pour migrer de PHP vers JSON, utilisez le script generateJsonI18n.php . Il déplacera les messages vers les fichiers JSON et remplacera le texte du fichier PHP en le faisant pointer vers les fichiers JSON. Ce code passe-partout est nécessaire pour la compatibilité arrière avec MediaWiki 1.19 . Il n'est pas utilisé dans les nouvelles extensions qui ne nécessitent pas la compatibilté avec MediaWiki 1.19.

Utiliser les messages

MediaWiki utilise un dépôt central des messages auxquels le code accède avec une clé. Ceci est différent de Gettext par exemple, qui ne fait qu'extraire des fichiers source, les chaînes de caractères traductibles. Le système basé sur les clés rend certaines choses plus faciles, comme affiner les textes originaux et tracer la modification des messages. La contrepartie est bien sûr que la liste des messages utilisés et la liste des textes source pour ces clés peuvent diverger. En pratique, ce n'est pas un gros problème et le seul vrai problème est que quelques fois des messages supplémentaires qui ne sont plus utilisés, sont encore présentés à la traduction.

Pour rendre les clés des messages plus gérables et facilement reconnaissables même avec grep, vous devez toujours les écrire totalement, sans trop vous fier à leur création dynamique. Vous pouvez concaténer des parties de clé de message si vous pensez que cela donne une meilleure structure à votre code, mais laissez un commentaire à côté avec une liste des clés résultantes possibles.

Voir aussi les conventions de codage. Par exemple :

// Messages utilisables ici :
// * myextension-connection-success
// * myextension-connection-warning
// * myextension-connection-error
$text = wfMessage( 'myextension-connection-' . $status )->parse();

Pour utiliser un message en JavaScript, vous devez le lister dans la définition de votre module ResourceLoader, dans la propriété "messages".

L'utilisation détaillée des fonctions des messages en PHP et en JavaScript se trouve sur API Messages . C'est une page de documentation importante, et vous devriez l'avoir lue AVANT d'écrire le code qui utilise des messages.

Sources des messages

Le code recherche les messages système depuis les sources suivantes :

  • Espace de noms MediaWiki. Ceci permet aux wikis d’adopter ou de remplacer tous leurs messages, quand les messages standards ne conviennent pas ou ne sont pas souhaités.
    • MediaWiki:Message-key est le message par défaut,
    • MediaWiki:Message-key/language-code est le message à utiliser quand un utilisateur a sélectionné une autre langue que la langue par défaut du wiki.
  • A partir des fichiers de messages :
    • Le noyau MediaWiki lui-même et la plupart des extensions les plus maintenues actuellement utilisent un fichier par langue, appelé zyx.json, où zyx est le code de la langue.
    • Certaines extensions plus anciennes utilisent un fichier de messages combiné contenant tous les messages dans toutes les langues, habituellement appelé MyExtensionName.i18n.php.
    • De nombreux wikis de la Fondation Wikimedia accèdent à certains messages de l’extension WikimediaMessages , leur permettant de standardiser les messages au travers des wikis WMF sans les imposer sur chaque installation de MediaWiki.
    • Seules quelques extensions utilisent d’autres techniques.

Mise en cache

Les messages système sont l'un des composants les plus significatifs de MediaWiki, principalement parce qu'ils sont utilisés à chaque requête web. Les fichiers PHP des messages sont longs, parce qu'ils contiennent des milliers de clés de messages et les valeurs. Charger ces fichiers (et éventuellement les fichiers multiples si la langue de l'utilisateur est différente de celle du contenu) a un coût énorme sur la mémoire et les performances. Un système agressif de mise en cache par niveau est utilisé pour réduire cet impact sur les performances.

MediaWiki possède beaucoup de mécanismes de mise en cache intégrés, ce qui rend le code quelque peu difficile à comprendre. Depuis la 1.16 il existe un nouveau système qui met en cache les messages soit dans les fichiers cdb ou dans la base de donnérs. Les messages personnalisés sont mis en cache dans le système de fichiers et dans memcached (ou équivalent), en fonction de la configuration.

La table ci-dessous donne un aperçu des paramètres concernés :

Emplacement du cache $wgLocalisationCacheConf
'store' => 'db'
 
'store' => 'detect'
(par défaut)
'store' => 'files'
 
'store' => 'array'
(expérimental depuis MW ≥ 1.26)
$wgCacheDirectory = false
(par défaut)
l10n cache table l10n cache table erreur (chemin non défini) erreur (chemin non défini)
= path l10n cache table système local de fichiers (CDB) système local de fichiers (CDB) système local de fichiers (tableau PHP)
Versions de MediaWiki :
1.27.0 – 1.27.2
Gerrit #Id3e2d2

Dans MediaWiki 1.27.0 et 1.27.1, l'auto-détection a été modifiée pour favoriser l'archivage du fichier. Dans le cas 'store' => 'detect' (cas par défaut), le fichier stocké est utilisé avec le chemin de $wgCacheDirectory . Si cette valeur n'est pas initialisée (cas par défaut), on utilise un répertoire temporaire déterminé par le système d'exploiration. Si le répertoire temporaire ne peut être identifié le dépôt de la base de données est utilisé comme solution de repli. Ceci a été annulé dans 1.27.2 et 1.28.0 à cause des conflits d'accès aux fichiers sur les hôtes partagés et des problèmes de sécurité (voir T127127 et T161453).

Trace des fonctions

Pour mieux décrire visuellement les niveaux du cache, il existe une fonction qui trace en marche arrière les méthodes qui ont été appelées pour récupérer les messages. Voir les sections ci-dessous pour l'explication de chaque niveau.

  • Message::fetchMessage()
  • MessageCache::get()
  • Language::getMessage()
  • LocalisationCache::getSubitem()
  • LCStore::get()

Cache des messages

La classe MessageCache est le niveau supérieur de la mise en cache des messages. Elle est appelée de la classe Message et renvoie le contenu final brut des messages. Ce niveau gère la logique suivante :

Le dernier point est important. Le repli de langue est une solution de secours qui permet à MediaWiki de choisir une autre langue si le message n'existe pas dans la langue demandée. Comme indiqué dans la section suivante, la plupart des replis de langue se produisent au niveau le plus bas. Néanmoins seul le niveau MessageCache vérifie qu'il n'y a pas de recouvrement de messages dans la base de données. Ainsi c'est ici qu'est faite l'intégration de messages redéfinis, de la base de données vers la base arrière. Si la base de données n'est pas utilisée, ce niveau entier peut être désactivé.

Cache d'internationalisation

Voir LocalisationCache.php

Classe LCStore

La classe LCStore est plutôt une implémentation d'arrière plan utilisée par la classe LocalisationCache pour mettre en cache les messages et les récupérer. Comme la classe BagOStuff utilisée pour la mise en cache générale dans MediaWiki, il existe différents types de caches (configurés en utilisant $wgLocalisationCacheConf) :

  • db (par défaut) - cache des messages de la base de données
  • file (par défaut si $wgCacheDirectory est défini) - utilise CDB pour mettre en cache dans un fichier local
  • accel - utilise APC ou un autre cache de code d'opération pour ranger les données

L'option file est utilisée par la Fondation Wikimedia, et elle est recommandée parce qu'elle est plus rapide que des accès à la base de données et plus fiable que le cache APC, particulièrement depuis que APC est devenu incompatible avec les versions 5.5 et ultérieures de PHP.

Ajouter de nouveaux messages

Choisir la clé du message

Voir aussi : Conventions de codage

La clé du message doit être globalement unique. Cela comprend le noyau de MediaWiki avec toutes les extensions et les habillages.

Pour le nom des messages, utilisez les minuscules, les nombres et les tirets '-'; la plupart des autres caractères sont parmi les moins pratiques et ceux qui ne fonctionnent pas du tout. D'après la convention MediaWiki, le premier caractère n'est pas sensible à la casse; ce qui n'est pas le cas des caractères qui suivent.

Pour le nommage, veuillez suivre les conventions globales ou locales. Pour les extensions, utilisez un préfixe standard, de préférence le nom de l'extension en minuscules, suivi d'un tiret « - ». Les exceptions sont :

Les messages utilisés par l'API
ils doivent commencer par apihelp-, apiwarn-, apierror-. Placez le préfixe de l'extension à la suite de ce préfixe. (Notez que ces messages doivent être dans un fichier séparé, habituellement sous includes/i18/api.)
Les messages liés aux connexions
ils doivent commencer par logentry-, log-name-, log-description.
Les droits utilisateur
la clé du nom à droite, tel qu'il est affiché sur Special:ListGroupRights doit commencer par right-. Le nom de l'action qui complète la phrase « Vous n’avez pas le droit de $2, pour la raison suivante : » doit commencer par action-.
Revisions tags
Les balises de révision : doivent commencer par tag-.
Special page titles
Les titres des pages spéciales : doivent commencer par special-.

Autres éléments à prendre en compte pour créer des messages

  1. Assurez-vous de traiter correctement le message (analyse syntaxique, substitution des {{, échappements pour le HTML, etc.)
  2. Si votre message fait partie du noyau, il doit être ajouté habituellement à languages/i18n/en.json, bien que certains composants tels que Installer, les balises EXIF, et ApiHelp possèdent leurs propres fichiers de messages.
  3. Si votre message appartient à une extension, ajoutez-le au fichier i18n/en.json ou au fichier en.json dans le sous-répertoire ad'hoc. En particulier les messages d'API qui ne sont vus que des développeurs et non pas par la plupart des utilisateurs finaux, se trouvent habituellement dans un fichier séparé, tel que i18n/api/en.json. Si une extension possède un grand nombre de messages, vous pouvez créer des sous-répertoires sous i18n. L'ensemble des répertoires de messages, y compris le répertoire i18n/ par défaut, doivent être listés dans la section MessagesDirs de extension.json ou dans la variable $wgMessagesDirs .
  4. Arrêtez-vous et analysez les mots du message. Est-ce suffisamment clair ? Est-ce que cela peut prêter à confusion ? Demandez les commentaires des autres développeurs ou des traducteurs si possible. Suivez les directives de traduction.
  5. Ajoutez la documentation à qqq.json dans le même répertoire.
  6. The sequence of the messages in the file should roughly conform to the features of your project. Put messages from the same feature next to each other. This helps translators stay focused and be efficient and consistent.
  7. Put the messages that are expected to be the most basic and the most frequently used in the beginning of the file, and the messages that are rarer and more technically advanced towards the end.


Messages à ne pas traduire

  1. Ignored - les messages ignorés sont ceux qui n'existent que dans le fichier des messages en anglais. Certains messages n'ont pas besoin d'être traduits car ils référencent simplement d'autres messages ou des fonctions indépendantes de la langue, par exemple un message de « {{SITENAME}} » .
  2. Optional - les messages facultatifs peuvent être traduits seulement s'ils sont modifiés dans la langue cible.

Pour marquer de tels messages :

Supprimer les messages existants

Supprimez-les de en.json et de qqq.json. Ne vous préoccupez pas des autres langues. Les mises à jour à partir de translatewiki.net les gèreront automatiquement.

En plus, vérifiez si le message apparaît quelque part dans la configuration translatewiki, par exemple dans la liste des messages optionnels ou celle des messages les plus utilisés (un simple git grep est suffisant). Supprimez-les de ces listes si nécessaire.

Modifier les messages existants

  1. Pensez à mettre à jour la documentation des messages.
  2. Mettez à jour les clés des messages si les anciennes traductions ne correspondent plus à la nouvelle signification. Cela comprend également les modifications dans le traitement des messages (analyse syntaxique, échappement, paramètres, etc.). Améliorer le contenu d'un message sans le modifier techniquement n'est habituellement pas un motif pour en changer la clé. Sur translatewiki.net, les messages seront marqués 'Désuets' afin d'être pris en compte par les traducteurs. Il n'est pas nécessaire de contacter l'équipe i18n ni de faire une demande de support pour modifier la clé d'un message. Néanmoins, si vous avez des conditions particulières ou des questions, posez-les sur #translatewiki connect ou sur les pages du support de translatewiki.net .
  3. Si l'extension est prise en charge par translatewiki.net , ne modifiez que le message source en anglais et / ou la clé, ainsi que l'entrée qui l'accompagne dans qqq.json. Si besoin, l'équipe translatewiki.net fera la mise à jour des traductions en les marquant 'désuètes' et en nettoyant le fichier ou en renommant les clés là où c'est possible. Cela s'applique également lorsque vous ne modifiez que des éléments tels que les balises HTML que vous pouvez mettre à jour dans les autres langues sans avoir besoin de les connaître. La plupart des ces actions se déroulent dans translatewiki.net et se retrouveront dans Git le lendemain.

Documentation des messages

La documentation des messages utilise le code de pseudo-langage qqq. C'est l'un des codes ISO 639 réservé pour l'utilisation personnelle. Là, nous ne gardons pas les traductions de chaque message, mais nous rassemblons les phrases en anglais concernant chaque message : pour indiquer où il est utilisé, pour donner des indications sur la manière de le traduire, pour lister et décrire ses paramètres et le relier aux autres messages avec lesquels il a un rapport, etc. Dans translatewiki.net, ces informations sont affichées aux traducteurs lors de la traduction des messages.

Les programmeurs doivent documenter soigneusement chaque message. La documentation du message est une ressource essentielle – pas seulemnt pour les traducteurs, mais pour tous les mainteneurs du module. A chaque fois qu'un message est ajouté au logiciel, il faut ajouter aussi son entrée qqq correspondante; les versions qui ne le font pas sont marquées « V-1 » jusqu'à ce que la documentation soit ajoutée.

La documentation dans les fichiers qqq doit être mise à jour directement lors de l'ajout de nouveaux messages, ou lors de la modification d'un message existant en anglais qui en implique la réactualisation, par exemple pour l'ajout ou la suppression de paramètres. Dans les autres cas, la documentation doit habituellement être mise à jour dans translatewiki. Chaque chaîne de documentation est accessible avec https://translatewiki.net/wiki/MediaWiki:message-key/qqq, comme s'il s'agissait d'une traduction. Ces modifications seront exportées vers les répertoires source en même temps que les traductions.

Les informations utiles que vous devez faire figurer dans la documentation comprennent :

  1. la manière de traiter le message (analyse syntaxique, échappement, texte brut).
  2. le type utilisé pour les paramètres avec des exemples de valeurs.
  3. les endroits où le message est utilisé (pages, positions dans l'interface utilisateur).
  4. la manière dont le message est utilisé et où (un titre de page, le texte d'un bouton, etc.).
  5. quels autres messages sont utilisés avec le message courant, ou à quels autres messages celui-ci fait référence.
  6. tout autre complément qui précise ce message affiché dans son contexte, mais pas quand il est traité isolément (ce qui est le cas pour la traduction).
  7. si nécessaire, la grammaire à préciser. Par exemple, « open » en anglais désigne à la fois un verbe et un adjectif. Dans beaucoup d'autres langues les mots sont différents et il est impossible de traduire correctement si l'on ne sait pas de quoi il s'agit.
  8. les adjectifs qui décrivent des choses, tels que « désactivé » , « ouvert » ou « bloqué », doivent toujours indiquer à quoi ils se rapportent. Dans beaucoup de langues les adjectifs doivent avoir le genre du nom auquel ils se rapportent. Il est aussi possible que différentes sortes de choses aient besoin de différents adjectifs.
  9. indiquer si le message a des propriétés spéciales par exemple s'il s'agit d'un nom de page, ou s'il ne doit pas être traduit directement mais adapté à la culture ou au projet.
  10. indiquer si le message apparaît avec d'autres messages, par exemple dans une liste ou un menu. Les termes ou la grammaire des mots devraient alors être les mêmes que celle des messages voisins. De même, les éléments d'une liste doivent être en rapport avec la tête de liste.
  11. indiquer les parties du message qui ne doivent pas être traduites, comme les noms des espaces de noms génériques, les URLs ou les balises.
  12. expliquer les mots potentiellement pas clairs, par exemple les abbréviations, comme « CTA », ou le jargon spécifique, comme « template », « suppress » ou « stub ». (Notez qu'il vaut mieux éviter de tels mots en premier !)
  13. Les captures d'écran sont très utiles. Ne découpez rien – une image de l'écran complet avec le message affiché nous donne le contexte complet et peut être réutilisée pour plusieurs messages.

Quelques points supplémentaires :

  • Rappelez-vous que très très souvent les traducteurs traduisent les messages sans être au courant du logiciel.
  • Dans pratiquement tous les cas, les traducteurs n'ont aucune information du contexte, ni du module, ni des autres messages qui vont avec.
  • Le plus souvent, il est inutile de reformuler simplement le message dans la documentation.
  • N'utilisez pas le jargon des développeurs comme « nav » ou « comps ».
  • Envisagez l'écriture d'un glossaire pour les termes techniques utilisés dans votre module. Si vous le faites, créez un lien dessus pour le référencer dans la documentation des messages.

Vous pouvez référencer d'autres messages en utilisant leur {{msg-mw|message key}}. Faites ceci si certaines parties de messages sont issues d'autres messages (quand cela n'est pas possible autrement), ou lorsque certains messages sont affichés ensemble ou dans un même contexte.

translatewiki.net dispose de quelques modèles par défaut pour la documentation :

  • {{doc-action|[...]}} - pour les messages action-
  • {{doc-right|[...]}} - pour les messages right-
  • {{doc-group|[...]|[...]}} - pour les messages concernant les groupes d'utilisateurs (group, member, page, js et css)
  • {{doc-accesskey|[...]}} - pour les messages accesskey-

Voir les pages des modèles pour plus d'information.

Conseils pour internationaliser

En plus de la documentation, les traducteurs demandent aux développeurs de prendre en compte certains points afin de faciliter leur travail et le rendre plus efficace et permettre ainsi un bonne et fidèle traduction dans toutes les langues. Même si vous n'avez qu'à ajouter ou modifier les messages en anglais, ne perdez pas de vue les besoins de toutes les langues. Chaque message est traduit dans plus de 300 langues et ceci doit se faire de la meilleure manière possible. L'implémentation correcte de ces points vous aidera souvent aussi à mieux écrire les messages en anglais.

Localisation#Help_and_contact_info liste les endroits principaux où vous pouvez trouverl'assistance de personnes expérimentées connaissant i18n.

Utilisez correctement les paramètres des messages et les sélecteurs

C'est un prérequis pour l'écriture correcte de vos messages.

Evitez la réutilisation des messages

Les traducteurs ne recommandent pas la réutilisation des messages. Ceci peut sembler contre-intuitif, car le fait de copier et dupliquer du code est habituellement une mauvaise pratique, mais dans le cas des messages sytème c'est souvent nécessaire. Bien que deux concepts puissent être exprimés par le même mot en anglais, cela ne signifie pas nécessairement qu'il peuvent être traduits par le même mot en fonction de la langue. « OK » est un bon exemple : en anglais ceci est utilisé pour le texte d'un bouton générique, mais dans certaines langues on préfère avoir un texte qui soit en phase avec l'opération que le bouton réalise. Un autre exemple est pratiquement n'importe quel adjectif : un mot tel que « multiple » varie selon le genre dans différentes langues, donc vous ne pouvez pas le réutiliser pour décrire plusieurs choses différentes, et vous devez créer plusieurs messages distincts.

Si vous ajoutez plusieurs messages identiques, ajoutez également la documentation correspondante pour décrire le contexte des différences. Ne vous préoccupez pas du travail supplémentaire des traducteurs. La mémoire de traduction aide beaucoup en cela en gardant la souplesse d'avoir différentes traductions si nécessaire.

Eviter les messages fragmentés ou sous forme de 'patchwork'

Les langues possèdent différentes organisations des mots et des règles grammaticales et syntaxiques complexes. Il est très difficile de traduire des messages de type « lego », c'est à dire des messages formés à partir de plusieurs morceaux de texte, éventuellement avec des indirections (appelés aussi « concatenations de chaînes » ).

Il est préférable que chaque message soit une phrase complète. Plusieurs phrases peuvent habituellement être combinées beaucoup plus facilement à l'intérieur d'un bloc de texte si besoin. Si vous souhaitez combiner plusieurs chaînes en un seul message, passez-les en paramètre, afin que les traducteurs puissent les mettre dans l'ordre correct dans leur langue, au moment de la traduction.

Messages se référençant mutuellement

Une exception à la règle concerne les messages qui se référencent mutuellement : 'entrez le nom de l'auteur original dans le champs nommé {{int:name}} et cliquez sur {{int:proceed}} pour finaliser'. Ceci rend le message cohérent lorsqu'un développeur logiciel ou un opérateur du wiki change le nom du message ou modifie ce dernier ultérieurement. Sans l'astuce du int, les développeurs et les opérateurs devraient connaître tous les messages liés qui devraient être corrigés dès que l'un d'eux est modifié.

N'utilisez pas les termes et les modèles spécifiques à un projet particulier

MediaWiki est utilisé par diverses personnes à l'intérieur du mouvement Wikimedia et à l'extérieur également. Bien qu'à l'origine il a été conçu pour une encyclopédie, il est maintenant utilisé pour toutes sortes de contenus. C'est pourquoi il faut utiliser des termes généraux. Par exemple, évitez les termes comme « article », et utilisez « page » à la place, à moins que vous soyez absolument sûr que la fonctionnalité que vous développez ne sera utilisée que sur un site où les pages seront appelées « article ». N'utilisez pas « village pump » car c'est le nom de la page communautaire de la Wikipedia anglophone, mais plutôt à la place, un nom générique tel que « page de discussion » de la communauté.

N'espérez pas qu'un modèle particulier soit présent sur tous les wikis. Les modèles sont locaux aux wikis. Ceci s'applique à la fois aux messages source et à leurs traductions. Si un message utilise des modèles, ils ne fonctionneront que s'ils ont été créés sur CHACUN des wikis où la fonctionnalité est déployée. Mieux vaut éviter à tout prix l'utilisation des modèles dans les messages. Si vous devez absolument les utiliser, documentez cela clairement dans la documentation du message et dans les instructions d'installation de l'extension.

Séparer l'heure de la date dans les phrases

Certaines langues doivent insérer quelque chose entre la date et l'heure, qui dépend grammatiquement des autres mots de la phrase. Ainsi on ne pourra pas combiner la date et l'heure. D'autres personnes pourront trouver que la combinaison est pratique, ainsi la meilleure façon est habituellement de passer trois valeurs de paramètres (date/heure, date, heure) dans de tels cas et pour chaque traduction, de laisser inutilisées soit la première valeur soit les deux dernières selon les besoins.

Évitez {{SITENAME}} dans les messages

{{SITENAME}} présente plusieurs désavantages. Cela peut être ce que l'on veut (un acronyme, mot, courte phrase, etc.) et en fonction de la langue, utiliser {{GRAMMAR}} sur chaque occurrence. Cela est indépendant du fait que chaque message qui a {{SITENAME}} nécessite une relecture dans la plupart des langues du wiki pour chaque nouveau wiki sur lequel votre code est installé. Dans la plupart des cas, quand il n'y a pas de configuration générale GRAMMAR pour une langue, les opérateurs wiki devront ajouter ou modifier le code PHP de sorte à ce que {{GRAMMAR}} fonctionne pour {{SITENAME}} . Ceci nécessite à la fois de plus grandes compétences et plus de compréhension qu'autrement. Il est plus pratique d'avoir des références génériques comme « ce wiki » . Cela n'empêche pas les installations de modifier localement ces messages pour utiliser {{SITENAME}}, mais au moins elles n'y sont pas obligées et peuvent retarder leur adaptation après que le wiki soit actif et utilisé.

Eviter les références au rendu visuel et aux positions

Ce que vous voyez dépend de l'habillage que vous utilisez. Le plus souvent, la présentation des écrans pour les langues s'écrivant de gauche à droite est mirrorée comparativement à celle pour les langues s'écrivant de droite à gauche, mais cela n'est pas toujours vrai, et pour certaines langues et certains wiki, pas complètement. Les équipements tenus à la main, les écrans étroits et autres peuvent afficher des blocs les uns au dessous des autres pouvant se retrouver côte à côte sur des écrans plus larges. Comme les scripts JavaScript et les gadgets du site - tout comme ceux de l'utilisateur - peuvent et cachent effectivement des morceaux ou déplacent partout les éléments et d'une manière imprévisible, il n'y a pas de manière fiable pour prédire ce que devient l'affichage final.

C'est très mauvais de lier l'information à afficher aux langues du contenu, parce que la langue de l'interface utilisateur peut ne pas correspondre à la langue du contenu de la page, et que l'affichage peut résulter d'un mélange des deux, en fonction des circonstances. Les agents utilisateur non visuels tels que les lecteurs d'écran acoustiques ou les autres équipements auxilliaires ne connaissent même pas la notion d'affichage. Ainsi, dans la majorité des cas vous ne devez pas faire référence aux positions visuelles de l'affichage bien que les termes sémantiques de celui-ci peuvent encore être utilisés (« étapes précédentes du formulaire », etc.).

MediaWiki ne prend pas en charge l'affichage de messages différents ou des fragments de messages basés sur la directionalité courante de l'interface (voir T30997).

Les navigateurs futurs ainsi que le support de MediaWiki pour l'écriture de haut en bas d'Orient et d'Asie du Nord [1] feront que l'affichage sur écran sera plus imprévisible, avec au moins 8 affichages possibles (position de départ à gauche ou à droite, en haut ou en bas, en fonction de là où on commence).

Eviter les références aux couleurs de l'écran

La couleur dans laquelle est faite le rendu dépend de plusieurs facteurs y compris de l'habillage : les scripts JavaScript et les gadgets du site et ceux de l'utilisateur, ainsi que l'agent utilisateur local la réécrasent pour des raisons d'accessibilité ou de limitation technologique. Les agents utilisateur non visuels tels que les lecteurs d'écran acoustiques ou les autres équipements auxilliaires ne connaissent même pas la notion de couleur. Ainsi, vous ne devez pas évoquer les couleurs d'écran. (De même vous ne devez pas vous fier à la couleur uniquement comme mécanisme pour informer l'utilisateur de l'état, pour la même raison).

Avoir les éléments des messages avant et après chaque champ de saisie

Ceci est une règle suggérée et elle n'est pas encore devenue un standard du développement MediaWiki.

Alors que l'anglais permet l'utilisation efficace de l'interrogation sous la forme élément-deuxPoints-champsD'entrée, beaucoup d'autres langues ne le font pas. Même en anglais, vous souhaitez souvent utiliser « Distance: ___ mètres » plutôt que « Distance (en mètres): ___ ». En laissant de côté les éléments ‎<textarea>, vous devez penser à chaque champs d'entrée en respectant le motif « Distance: ___ mètres » . Donc :

  • créez deux messages, même si le 2nd est vide en anglais et certaines autres langues, ou
  • permettez l'insertion des champs de saisie en utilisant les paramètres $i .

Evitez le marquage HTML non traduit dans les messages

Les balises HTML qui n'ont pas besoin d'être traduites, comme les ‎<div>s englobants, les règles supérieures ou inférieures et similaires, ne doivent habituellement pas faire partie du message. Ils apportent une surcharge inutile aux traducteurs, augmentent la taille des fichiers, et créent le risque d'être modifiés accidentellement ou d'être sautés par le processus de traduction. De manière générale, évitez le HTML directement dans les messages si vous le pouvez.

Les messages sont souvent plus longs que vous le pensez !

En regardant un peu les fichiers des messages des langues étrangères, vous ne trouverez presque jamais des messages plus courts que les messages chinois, rarement plus courts que les messages anglais, et habituellement plus longs que les messages anglais.

Particulièrement dans les formulaires, devant les champs de saisie, les messages anglais ont tendance à être laconiques et courts. Souvent ceci n'est pas conservé dans les traductions. Le vocabulaire technique présent en anglais peut être absent dans les autres langues et demander l'utilisation de plusieurs mots ou même des phrases complètes pour expliquer certains concepts. Par exemple le message anglais « TSV file: » pourrait devoir être traduit dans une langue in extenso :

Veuillez entrer ici un nom qui représente une collection de données informatiques composée d'une série organisée séquentiellement de lignes dactylographiées qui elles-même sont organisées comme une série de champs informels chacunes, où les champs d'information sont fermés, séparés chacuns par un signe unique équivalent à celui qui fait déplacer le charriot d'une machine à écrire vers la position suivante prédéfinie. Commençons : _____ (merci)

C'est vrai que c'est un exemple extrême mais cela vous donne une idée. Imaginez cette phrase en colonne dans laquelle chaque mot est seul sur une ligne, et que le champs d'entrée est centré verticalement dans la colonne suivante. :-(

Eviter d'utiliser des mots très proches, similaires, ou identiques pour désigner des choses ou des concepts différents

Par exemple, les pages peuvent avoir d'anciennes révisions (correspondant à une date spécifique, une heure et un contenu), qui comprennent les versions passées de ladite page. Vous pouvez utiliser les mots revision et version de manière interchangeable. Un problème apparait lorsque les pages versionnées sont relues, et que la révision, c'est à dire le processus de relecture, est également mentionné. Cela ne pose pas de problème particulier lorsque les deux synonymes de la « révision » ont des traductions différentes. Néanmoins il ne faut pas vous fier à cela. Il vaut mieux éviter l'utilisation simultanée de révision avec version, pour éviter d'apporter la confusion.

Les mots de base peuvent avoir des connotations imprévues, ou ne pas exister du tout

Certains mots sont difficiles à traduire à cause de leur utilisation spécique dans MediaWiki. Certains peuvent ne pas être traductibles du tout. Par exemple le mot « utilisateur  » n'existe pas dans plusieurs langues pour désigner « quelqu'un qui se sert de quelque chose  ». De la même façon, dans le dialecte kölsch les mots anglais « namespace » (espace de noms) et « apartment » (appartement) se traduisent avec le même mot. Aussi, en kölsch on dit « corroborator et participant » (collaborateur et participant) en un seul mot car toute référence à « utiliser » impliquerait trop systématiquement « abuser ». Le terme « ferme de wikis » (wiki farm) est traduit comme « étable pleine de wikis » car si on utilise « ferme » simplement on est en contradiction avec les mots de la langue, on ne comprend pas, etc..

Attendez-vous à rencontrer des mots non traduits

Ceci est une règle suggérée et elle n'est pas encore devenue un standard du développement MediaWiki.

Il n'est pas rare que les noms propres, les noms des balises, etc. et les termes informatique en anglais ne soient pas traduits, et sont à la place pris comme des mots d'emprunt ou des mots étrangers. Dans le dernier cas, certains traducteurs particulièrement fastidieux peuvent marquer de tels mots comme s'ils appartenaient à une autre langue avec le balisage HTML, comme <span lang="en"></span>.

Vous pouvez vous assurer que votre gestionnaire de sortie des messages laisse inchangé un tel balisage, malgré les risques évidents de sécurité.

Permettre le marquage explicatif en ligne

Ceci est une règle suggérée et elle n'est pas encore devenue un standard du développement MediaWiki.

Il existe quelque fois dans les langues cible des abbréviations, des termes techniques ou des mots généralement ambigus qui ne peuvent pas être immédiatement compris des nouveaux arrivants mais qui sont évidents pour les utilisateurs expérimentés d'ordinateurs . Pour éviter l'encombrement de l'écran par de longues explications et ne pas laisser les nouveaux arrivants bloqués, les traducteurs peuvent choisir d'ajouter des explications comme les annotations ‎<abbr>, à la manière des navigateurs lorsque vous les survolez avec la souris.

Par exemple, le message du noyau de MediaWiki exif-orientation-8 concernant la rotation d'image, qui en anglais est simplement « Rotated 90° CW », en arabe marocain est traduit par :

mḍwwer 90° <abbr title="Ĝks (ṫ-ṫijah) Ĝaqarib s-Saĝa">ĜĜS</abbr>

donne :

mḍwwer 90° ĜĜS

en expliquant l'abbréviation de « counter clockwise » (sens de rotation rétrograde) lorsque c'est nécessaire.

Vous pouvez vous assurer que votre gestionnaire de sortie des messages laisse inchangé un tel balisage, même si le message original ne l'utilise pas.

Utiliser les balises ‎<code>, ‎<var>, et ‎<kbd> à bon escient

Lorsqu'on parle de paramètres techniques, de valeurs, ou d'entrées au clavier, marquez les respectivement en tant que tel en utilisant les balises HTML ‎<code>, ‎<var>, ou ‎<kbd>. Ainsi, ils sont typographiquement mis en valeur par rapport au texte normal. Cela clarifie leur sens pour les lecteurs, évitant la confusion, les erreurs et les mauvaises interprétations. Vérifiez que votre gestionnaire de messages permet un tel marquage.

Symboles, deux points, crochets, etc. faisant partie des messages

Beaucoup de symboles sont localisables également. Certains scripts utilisent d'autres types de crochets que ceux des scripts latins. Un deux-points peut ne pas être approprié après une étiquette ou une invite de saisie dans certaines langues. L'inclusion de ces symboles dans les messages aide à faire des traductions meilleures et moins anglo-centrées, et réduit également la taille du code.

Il existe par exemple différentes conventions pour les apostrophes utilisées en « norvégien », » suédois», »danois«, „allemand“, et 「japonais」.[2]

Si vous avez besoin d'envelopper le texte entre des parenthèses localisées, des crochets, ou des guillemets, vous pouvez utiliser les messages parentheses ($1) ou brackets [$1] ou quotation-marks "$1" de la manière suivante :

wfMessage( 'parentheses' )->rawParams( /* text to go inside parentheses */ )->escaped()
wfMessage( 'brackets' )->rawParams( /* text to go inside brackets */ )->escaped()
wfMessage( 'quotation-marks' )->rawParams( /* text to go inside quotation marks */ )->escaped()

N'espérez pas que les symboles et la ponctuation survivent à la traduction

Les langues écrites de droite à gauche (contrairement à l'anglais) permutent habituellement les symboles des flèches utilisées pour les liens « suivant » et « précédent », et leur placement relativement au texte du message peut ou ne peut pas être permuté également. Vous pouvez traduire les points de suspension par « etc. », ou avec des mots. Les points d'interrogation, d'exclamation, et les deux-points seront mis ailleurs qu'en fin de phrase, ou pas utilisés, ou utilisés deux fois. Comme conséquence, ils doivent toujours faire partie de votre message et ne tentez pas de les insérer par programme.

Utiliser les arrêts complets

Terminez absolument les phrases normales avec des caractères d'arrêt. C’est souvent la seule indication qu’a le traducteur pour savoir qu’il ne s’agit pas de titres ni d’éléments de liste qui nécessiteraient une traduction différente.

Ancre des liens

Wikicode des liens

L'ancre des liens peut être déclarée dans les messages à travers différentes techniques :

  1. via le wikicode : … [[une page wiki|ancre]] …,
  2. via le wikicode : … [une-url ancre] …, or
  3. le texte de l'ancre est un message appartenant à l'espace de noms MediaWiki. Evitez-le !

Le dernier cas est souvent difficile voire impossible à gérer pour les traducteurs; il faut éviter les messages fragmentés et ne pas les assembler en 'patchwork' ici également. Assurez-vous que « some-url » ne contient pas d'espaces.

Utiliser des ancres ayant des noms significatifs

Faites attention à votre texte. Les ancres des liens jouent un rôle important pour l'accès aux pages du moteus de recherche – à la fois les mots liés ainsi que l'ancre cible. Assurez-vous aussi que l'ancre décrit bien la page cible. Évitez toujours les mots communs et génériques. Par exemple, « Cliquez ici » est absolument interdit [3] car les pages cibles ne concernent pratiquement jamais « Cliquez ici ». Il ne faut pas non plus mettre cela dans des phrases entouré de liens car « ici » n'était pas l'endroit à cliquer. A la place, utilisez des mots représentant des actions précises pour dire ce qu'obtiendra l'utilisateur en ouvrant le lien, comme « Vous pouvez téléverser un fichier si vous le souhaitez. »

Voir aussi Aider les utilisateurs à prédire où ils vont, la navigation en aveugle, et Les raisons principales de ne pas utiliser 'Cliquez ici' comme texte de lien.

Eviter le jargon et l'argot

Evitez d'utiliser le jargon des développeurs ou des termes trop pointus dans les messages. Essayez d'avoir un langage simple à chaque fois que c'est possible. Evitez d'utiliser « OK » « avec succès » « échec » « erreur durant », etc., si vous voulez signaler à l'utilisateur que quelque chose est arrivé ou ne s'est pas passé. Cela vient du point de vue des développeurs qui considèrent tout comme vrai ou faux, mais les utilisateurs veulent savoir habituellement simplement ce qui s'est passé ou ne s'est pas déroulé et ce qu'ils doivent faire dans ces cas (si nécessaire). Donc :

  • « Ce fichier a été renommé avec succès » → « Ce fichier a été renommé »
  • « Echec du renommage du fichier » → -> « Un fichier de même nom existe déjà. Utiliser un nom différent ».

Faites attention aux caractères espace et aux retours à la ligne

Les messages traduits de MediaWiki sont habituellement traduits sur le wiki, soit lors d'opérations wiki sur les wikis actifs, ou par des traducteurs sur translatewiki.net. Soyez conscient de la manière dont les espaces vont influer sur les éditeurs (particulièrement s'ils se trouvent au début ou à la fin de votre message) :

  • Les espaces et les passages à la ligne (saut de ligne) présents à la fin du message sont toujours enlevés automatiquement par l'éditeur de wikicode. Par conséquent votre message ne doit pas se terminer par un espace ni un passage à la ligne car ils seront perdus quand le message sera modifié sur le wiki.
  • Les espaces et les sauts de ligne en tête de message - eux - ne sont pas automatiquement supprimés, mais peuvent disparaître par accident lors des modifications; ceci doit donc être évité.

Commencez et terminez votre message avec du texte actif; si vous avez besoin d'une nouvelle ligne ou d'un saut de paragraphe autour, votre code englobant doit accepter l'ajout au texte renvoyé.

Certains messages ont besoin d'un espace à la fin pour séparer les mots (formé simplement d'un caractère espace dans la plupart des langues). Pour prendre en charge ces cas d'utilisation, les entités HTML suivantes sont autorisées dans les messages et transformées en caractères actuels, même si autrement le message n'autorisait pas le formatage wikicode ou HTML :[4]

Sur une note associée, tout autre élément de syntaxe affecté par les transformations avant enregistrement doit également ne pas être utilisé dans les messages, car il sera transformé quand le message sera modifié sur le wiki.

Utiliser la capitalisation standard

La capitalisation indique aux traducteurs ce qu'ils doivent traduire, comme les mots isolés, les listes d'éléments ou les menus, les phrases, ou des phrases complètes. La capitalisation correcte (standard) peut aussi jouer un rôle dans l'accès à vos pages par les moteurs de recherche. MediaWiki utilise la casse des phrases (The quick brown fox jumps over the lazy dog) dans les messages d'interface.

Rappelez-vous toujours que beaucoup des systèmes d'écriture ne possèdent pas de lettres capitales du tout, et que ceux qui les ont, les utilisent différemment de l'anglais. C'est pourquoi il ne faut pas utiliser que des majuscules pour l'emphase. Utilisez en CSS, ou HTML ‎<em> ou ‎<strong> pour ceci :

Emphase

Dans un texte normal l'emphase, c'est à dire la mise en valeur comme gras, italiques ou équivalent, doit faire partie du message lui-même. Les conventions locales pour la mise en valeur sont souvent différentes, particulièrement pour certains scripts asiatiques qui ont les leurs. Les traducteurs doivent pouvoir adapter l'emphase à la langue cible et aux domaines. Essayez d'utiliser « ‎<em> » et « ‎<strong> » dans votre interface utilisateur pour permettre le balisage sur la base des langues ou des scripts.

Les affichages modernes des styles anglais et européens utilisent de moins en moins l'emphase. Utilisez-la néanmoins encore dans votre documentation de message, car elle peut fournir des informations intéressantes sur la manière de traduire. L'emphase peut et doit être utilisée dans les autres contextes culturels selon le cas, étant entendu que les traducteurs la connaissent.

Voir aussi