Rendre les plugins et les thèmes prêts pour la traduction • WPShout

L'internationalisation rend WordPress accessible dans d'autres langues, et c'est un incontournable pour les travaux destinés à une large diffusion.

Alors que WordPress continue de se développer, non seulement dans les pays anglophones mais dans le monde entier, une tension monte: la plupart de la programmation se fait en anglais et la plupart des modules complémentaires WordPress (plugins ou thèmes) sont écrits avec des chaînes anglaises. Cependant, de nombreux utilisateurs de WordPress – maintenant nettement plus de 50% – ne sont pas des anglophones de première langue.

C’est pourquoi, au cours de la dernière décennie, nous avons vu de plus en plus de discussions et de soutien à l’internationalisation. L'internationalisation rend WordPress accessible dans d'autres langues, et c'est un incontournable si vous travaillez sur des thèmes ou des plugins pour une large distribution.

Remarque sur les termes: «i18n» et «l10n»

Parce que cela m'a pris un certain temps à comprendre: vous verrez fréquemment «internationalisation» abrégé en «i18n». En effet, entre l’ouverture «i» et le «n» final du mot internationalisation, dix-huit lettres existent. Vous sautez donc 18 des 20 lettres du mot et vous les remplacez par le chiffre du compte.

Localisation, le mot pour profiter de l'internationalisation, est souvent abrégé en l10n, avec la même logique. Encore une fois, «l-dix-n» ne signifie rien de spécial en soi; l'épeler de cette façon est juste une chose numérique intelligente.

Les étapes de l'internationalisation du code WordPress

Faciliter la traduction d'un plugin ou d'un thème, avec ses chaînes anglaises natives pour les éléments d'interface, nécessite trois étapes:

1. Choisissez, déclarez et utilisez un "domaine de texte".
2. Utilisez les fonctions appropriées avec vos chaînes et ce domaine de texte.
3. Cela vous permet de générer des fichiers de traduction.

Armés de ces fichiers de traduction, les gens peuvent traduire votre plugin ou votre thème.

Qu'est-ce qu'un «domaine de texte» WordPress?

Un domaine de texte est un moyen de séparer un ensemble de «chaînes à traduire» des autres chaînes dans l'environnement plus large.

Un domaine de texte est «l'espace de noms de traduction» pour votre plugin ou thème. C'est un moyen pour WordPress, votre plugin ou votre thème de séparer sa liste de "chaînes à traduire" des autres chaînes qui pourraient devoir être traduites dans d'autres parties de l'environnement plus large.

Pourquoi un domaine de texte est-il nécessaire ou utile? Parce que différentes chaînes peuvent signifier des choses différentes dans différents plugins ou thèmes. Par exemple, "Allons-y!" peut signifier «Créer un compte d'adhésion» dans un contexte et «Lancer l'enquête» dans un contexte différent.

Vous déclarez donc un domaine texte, et vous l'utilisez avec tous vos «gettext» ou fonctions de traduction, ce que nous expliquons en détail dans la section suivante. Ce n’est pas trop difficile. (Le projet gettext établi sous-tend le fonctionnement de l'ensemble du système de traduction WordPress.)

Vous souhaiterez répertorier votre domaine de texte dans le bloc de commentaires principal de votre plug-in ou thème, situé dans style.css pour les thèmes, ou dans le fichier PHP principal de votre plugin. Cela ressemble à ceci pour les plugins:

<? php
/ *
Nom du plugin: Pretend Plugin
[Other comment-block information goes here]
Domaine de texte: wpshout
* /

Ou comme ceci pour les thèmes:

/ *
Nom du thème: Thème semblant
[Other comment-block information goes here]
Domaine de texte: wpshout
* /

Fonctions Gettext: garder votre __ ()s, _e ()s, _X()le sable _n ()s Droit

Donc, pour rendre vos textes traduisibles, ils doivent passer par une fonction qui pourrait remplacer "Allons-y!" avec l'équivalent espagnol, coréen ou swahili. Et pour des raisons de commodité, WordPress donne à toutes les fonctions qui permettent d'atteindre cet objectif des noms très courts.

__ ()

Je pense à la fonction de double soulignement, __ () comme le maître. Son nom est le plus déroutant – mais son objectif fondamental est de faire exactement ce que j'ai décrit: permettre à toutes les chaînes d'être traduites dans une langue si elles le devraient. Vous l'utilisez en lui passant deux paramètres: votre chaîne et votre domaine de texte. Cela ressemblera donc à:

écho __(
    'WPShout est un excellent site WordPress!',
    «wpshout»
);

Écho automatique avec _e ()

Le double soulignement juste Retour la chaîne; vous devez en faire écho vous-même. Si cela vous ennuie, _e () peut vous aider: c'est l'équivalent de écho __(). Cela vous fait gagner quelques caractères, mais ne fait rien d’autre.

Notre exemple, encore une fois:

_e (
    'WPShout est un excellent site WordPress!',
    «wpshout»
);

Ensuite, vous abordez certains des points les plus fins de la traduction.

Fournir du contexte avec _X()

Premièrement, un mot ou une phrase est parfois assez ambigu. Imaginons qu'en tant que traducteur, on vous demande de simplement traduire le mot «post» en arabe. Eh bien, cela faisait-il référence à un nom, comme «un article WordPress»? Ou peut-être était-ce un nom, mais un lampadaire? Ou peut-être avez-vous voulu dire le verbe "publier", qui équivaut à "publier".

contrairement à __ ('Publier', 'wpshout') et _e ('Publier', 'wpshout'), lorsque vous laisseriez le traducteur incertain sur la signification, vous pouvez fournir un contexte avec le _X() une fonction. On dirait:

_X(
    'Publier',
    'verbe, comme dans "publier"',
    «wpshout»
);

La chaîne de paramètres du milieu n'est jamais présentée à l'utilisateur, mais sera montrée aux traducteurs pour les aider à comprendre. (A savoir également, un _ex() fonction existe, comme vous pouvez le deviner, les combinaisons des _e et _X fonctions: il imprime la chaîne traduite et annotée.)

Pluralisation avec _n ()

La pluralisation est un autre domaine où les langues se compliquent. En anglais, j'ai «1 commentaire» ou «3 commentaires». Pour en tenir compte, WordPress propose le _n () fonction, qui peut traiter la différence entre les deux.

En utilisant _n () nécessite généralement que vous passiez un autre appel, au printf () (ou sprintf – le s ça veut dire Retour une corde, tandis que printf fondamentalement échos pour vous) fonction. Ces fonctions – également nommées étrangement – remplacent un jeton dans une chaîne par une valeur qui leur est passée. Donc, pour utiliser notre exemple de commentaires, cela ressemblera à quelque chose comme:

printf (
    _n (
        'Un commentaire',
        '% s commentaires',
        $ commentaires,
        «wpshout»
    ),
    $ commentaires
);

Vous noterez que nous utilisons une valeur numérique, attribuée à la variable $ commentaires deux fois. Disons $ commentaires a une valeur de 3. La première utilisation de $ commentaires est pour _n pour déterminer la pluralisation à utiliser: puisque 3 est supérieur à 1, il choisira % s commentaires plutôt que 'Un commentaire'.

La deuxième utilisation est pour printf pour mettre réellement ce nombre dans la chaîne, en remplaçant le % s avec le 3 cette $ commentaires a été réglé sur. Nous allons donc imprimer "3 commentaires" dans ce cas.

Autres fonctions Gettext

Cela couvre tous les éléments essentiels des fonctions «gettext», mais il y en a d'autres à noter:

• esc_attr __ (), qui fera la même chose que __ (), mais il prendra soin de esc_attr () (échappement des attributs HTML) pour votre sécurité. (Il existe également esc_attr_e () et esc_attr_x (): ces auto-écho et autorisez les annotations, comme vous vous en doutez.)
• esc_html __ (): encore une fois, pour des raisons de sécurité, vous pouvez combiner votre échappement HTML avec votre traduction. (Et encore, esc_html_e () et esc_html_x () des variations existent.)
• _n_noop () qui «enregistre mais ne traduit pas». En d'autres termes, il fait la même chose que _n () avec «aucune opération». Pour plus de détails, ou simplement un aperçu intéressant des subtilités de la traduction, je peux vous renvoyer à cet article de Konstantin Kovshenin.

Remise des traductions en JavaScript avec wp_localize_script ()

Étant donné que les traductions dans WordPress sont gérées via PHP, vous devez transmettre vos chaînes traduites à vos utilisations JavaScript. Cela se fait via le wp_localize_script () une fonction. La fonction est extrêmement utile et très utilisée en dehors de la traduction, car elle permet de passer tout Valeur PHP ou variable en JavaScript. Mais la traduction est l'usage pour lequel elle a été nommée.

Dans tous les cas, vous utilisez wp_localize_script ainsi:

wp_localize_script (
    'wpshout-js',
    'chaînes',
    tableau (
        'hello' => __ ('Bonjour!', 'wpshout');
    )
);

Ensuite, pour accéder aux valeurs de votre JavaScript, vous allez faire quelque chose comme:

alert (strings.hello);

wp_localize_script () a trois paramètres:

1. La poignée que nous avons utilisée wp_enqueue_script () (ou wp_register_script ()) pour le JS que nous localisons
2. Le nom de l'objet JavaScript auquel nous voulons que nos traductions soient liées
3. Un tableau associatif des traductions, avec «index» ou nom de propriété comme clé et la valeur comme chaîne réelle à utiliser

La traduction elle-même est gérée par les mêmes fonctions PHP que nous avons abordées dans la dernière section.

Détails techniques: que sont les fichiers POT, PO et MO?

Jusqu'à présent, nous avons principalement parlé de programmation PHP. Mais il y a une partie secondaire de toute la gamme qui n'implique pas vraiment la création de PHP, et qui génère des fichiers de traduction. De nos jours, WordPress.org a rationalisé ce processus, mais il est bon de toujours comprendre les bases.

Cela a toujours été un point difficile. Lentement, l'écosystème WordPress commence à créer des solutions plus robustes, documentées et utiles pour gérer le travail réel de traduction – voir translate.wordpress.org et le blog Polyglot Make – mais cela reste un peu pénible pour un utilisateur moyen. Nous n'entrerons pas dans les détails ici car il s'agit d'un domaine en mutation, mais j'ai moi-même utilisé Poedit avec une satisfaction et un succès marginaux.

Quelle que soit la forme que vous avez utilisée pour créer, modifier et lire ces fichiers de traduction, il existe trois types principaux:

• Fichiers POT (.pot): fichiers maîtres pour un plugin ou un thème, qui ont rassemblé toutes les chaînes de votre __ ()le sable _ex()s, etc. Ceux-ci sont ensuite ramassés dans la génération de…
• Fichiers PO (.po), qui sont les traductions en clair de vos chaînes anglaises dans la langue cible. Vous en modifierez rarement un directement – le format comporte de nombreuses parties bruyantes et intimidantes – mais vous pouvez les ouvrir dans un éditeur de texte pour apporter des modifications rapides à la traduction.
• Fichiers MO (.mo): les traductions finales de l'anglais vers la langue cible qui sont réellement utilisées et lues par WordPress. Ce sont des fichiers binaires, donc pendant que vous en ouvrez un dans un éditeur de texte, il ne ressemblera à rien de ce que vous allez éditer … Vous devez en fait retourner au fichier PO et régénérer le fichier MO à partir de là.

Comme je l'ai dit, la génération et l'utilisation de ces fichiers est l'une des parties les plus difficiles d'i18n pour moi. Mais si votre thème ou plug-in se trouve dans le référentiel WordPress.org, ils se chargeront du fichier .pot pour vous, et vos traducteurs sauront probablement comment gérer le reste. Si vous avez besoin de plus de détails ou si vous souhaitez d'autres outils, consultez la page «Traduire WordPress».

Ce que nous avons appris sur l'internationalisation du code WordPress

Nous avons couvert les trois parties principales de la préparation de votre traduction de code WordPress: choisissez un domaine de texte, utilisez-le dans vos fonctions «gettext», puis récupérez le fichier POT pour créer vos fichiers PO et MO. Les étapes sont petites et réalisables, et elles ont un impact important pour les non-anglophones, ou ceux qui sont simplement plus à l'aise dans une langue différente qu'ils ont apprise plus tôt. Bon piratage!