Traduction de contenu¶

Commencer à traduire¶

Si vous souhaitez contribuer aux efforts de traduction de BeeWare, vous aurez besoin d'un compte sur Weblate. Créez un nouveau compte si vous n'en avez pas encore, puis faites-nous savoir que vous souhaitez participer aux traductions.

Vous avez deux possibilités pour nous faire savoir que vous aimeriez participer aux traductions :

Si vous êtes sur Discord, rejoignez le serveur BeeWare, et dirigez-vous vers le canal #translations.
Si vous n'êtes pas sur Discord, vous pouvez créer un nouveau problème sur le dépôt BeeWare.

Dans les deux cas, laissez un message contenant les informations suivantes :

Votre nom d'utilisateur pour Weblate
La langue dans laquelle vous envisagez de traduire le contenu

Une fois que nous aurons ces informations, nous vous ajouterons à l'équipe.

Ajouter une nouvelle traduction¶

Si la langue pour laquelle vous souhaitez apporter votre aide n'existe pas encore, il y a quelques étapes supplémentaires à franchir avant de pouvoir commencer :

Créer le fichier /docs/mkdocs.language-code.yml, avec le contenu spécifique à la langue.
Mise à jour de tox.ini pour inclure les commandes de compilation dans les nouvelles langues.
Mise à jour de /docs/config.yml pour inclure la langue sous extra : alternate:.

Les paragraphes suivants illustrent les changements nécessaires en prenant l'exemple de l'allemand ; une traduction en allemand existe déjà ; remplacez les références à l'allemand, de, ou tout autre contenu pour la langue que vous ciblez.

Un nouveau fichier de configuration MkDocs¶

Tout d'abord, créez un nouveau fichier nommé mkdocs.de.yml dans le répertoire docs, avec le contenu suivant :

INHERIT: config.yml
site_name: BeeWare Dokumentation
site_url: https://beeware.org/de
docs_dir: de

theme:
  language: de

extra:
  translation_type: machine

Voici ce qui se passe dans ce dossier :

Ce fichier hérite du contenu de la configuration de config.yml.
La valeur site_name est traduite.
La valeur site_url est l'URL du site du projet, suivie du code de la langue.
Le docs_dir doit être le code de la langue.
La valeur theme : language: doit être le code de la langue, comme spécifié par le thème MkDocs Material. Pour la plupart des langues, ce sera le même que le code de la langue docs_dir ; mais pour certaines (en particulier les langues avec des variantes locales comme zh_CN), il y a des différences.
Le extra : translation_type: doit être machine jusqu'à ce que la traduction atteigne 100% pour la première fois, à ce moment-là il doit être human. Elle passera de human à machine si elle descend en dessous de 90%.

Mise à jour de `tox.ini`¶

Vous devrez apporter plusieurs modifications au fichier tox.ini.

Vous ajouterez ce qui suit :

Le nouvel indicateur d'environnement de code de langue à la ligne d'en-tête qui commence par [testenv:docs, avec le code de langue précédé d'un -, sans espace, par exemple -de.
Le nouveau code linguistique exclut la première commande, qui commence par !lint, précédée de -!, sans espace, par exemple -!de.
Le code de la nouvelle langue à la fin de la ligne commençant par translate : build_po_translations.
Le code de la nouvelle langue à la fin de la ligne commençant par translate : update_machine_translations
Une nouvelle commande, commençant par exemple par de : build_md_translations pour l'allemand, après les autres commandes existantes spécifiques à la langue, qui fait correspondre le contenu de ces commandes avec le nouveau code de langue.
Le code de la nouvelle langue à la fin de la ligne commençant par "all,serve :`".

Mise à jour de `config.yml`¶

Ajoutez la langue à config.yml pour qu'elle apparaisse dans le sélecteur de langue de l'en-tête. Trouvez la section commençant par extra:, puis la sous-section commençant par alternate:. Pour l'allemand, vous devez ajouter ce qui suit :

    - name: Deutsch
      link: /de/
      lang: de

Le nom de la langue doit être traduit dans la langue. Le lien doit inclure les /.

La nouvelle langue est maintenant prête à être traduite.

Lignes directrices pour la traduction¶

Une fois que vous avez été ajouté à l'équipe, il est temps de vous connecter à Weblate et de commencer à travailler sur la traduction des chaînes de caractères.

Le ton ou la traduction mot à mot¶

Il est plus important de conserver le ton du texte anglais que de s'efforcer de le traduire mot à mot. Nous essayons d'être amicaux et un peu familiers dans notre contenu ; essayez d'en conserver l'esprit dans vos traductions.

Si le texte anglais contient une expression idiomatique forte, ne vous sentez pas obligé de conserver cette expression, s'il existe une expression analogue dans votre langue qui fonctionnerait tout aussi bien. Si le terme ou l'expression du texte anglais est particulièrement idiomatique ou argotique, n'hésitez pas à nous dire que nous devrions envisager de le modifier. Même pour les anglophones, les expressions idiomatiques et argotiques peuvent poser des difficultés. Il est parfois nécessaire de modifier le texte anglais afin de le rendre plus simple pour les traducteurs et les lecteurs.

Dois-je le traduire ?¶

Les éléments suivants ne doivent pas être traduits ou mis à jour :

Commandes. Par exemple, dans "You should run `briefcase create`.", seul "You should run" doit être traduit.
Espaces de noms, tels que les noms de classes, de méthodes ou d'attributs.
URL des liens. Les liens Markdown standards devraient apparaître dans Weblate comme [Texte du lien]{1}, où 1 est la position du lien dans la chaîne en référence à d'autres liens possibles. Si l'URL complète est incluse dans la chaîne, comme [Texte du lien](https://example.com), l'URL doit être ignorée pour la traduction.
Liens de référence contenant des noms de classes, de méthodes ou d'attributs. Ils doivent être laissés tels quels, y compris les antisèches. Toutes les parties de l'exemple de lien présenté ici ne seraient pas traduites.
```
[`Class.attribute`][Class.attribute]
```
Le contenu d'un lien de référence. Par exemple, link-content serait ignoré dans l'exemple suivant :
```
[Link text][link-content]
```
Directives Jinja. Il s'agit de tout contenu placé à l'intérieur de deux paires d'accolades correspondantes, ou d'une paire d'accolades correspondantes avec des signes de pourcentage à chaque extrémité. Note : L'inclusion d'un exemple de la syntaxe ici entraîne une tentative de rendu par le plugin Macros ; voir la documentation Macros pour des exemples.
Ancres personnalisées. Elles se trouvent après les en-têtes ou au-dessus d'un contenu, et sont formatées comme { #anchor }.
Syntaxe de l'admonition. Dans l'exemple suivant, le mot "admonition" ne doit pas être traduit. Cela vaut pour tous les types d'admonitions, y compris les notes, les avertissements, etc. Voir la section suivante pour plus d'informations sur la traduction du reste du contenu.
```
/// admonition | Page Title

Content.

///
```
Backticks. Ils sont destinés à rester des backticks ; ils sont utilisés pour formater à la fois le code en ligne et les blocs de code.
La syntaxe pour inclure du contenu externe. Il s'agit de tout ce qui se trouve sur la même ligne que -8<-, ou sur les lignes entre deux -8<- sur des lignes séparées.

Les éléments suivants devraient être traduits :

Texte du lien. Dans la syntaxe des liens, le texte vient avant l'URL, et est placé entre crochets, comme dans [Texte du lien](URL). Les liens Markdown standards devraient apparaître dans Weblate comme [Texte du lien]{1}, où 1 est la position du lien dans la chaîne en référence à d'autres liens possibles.
Texte du lien de référence. Par exemple, Link text serait traduit comme suit :
```
[Link text][link-content]
```
Titres et contenu des admonitions. Dans l'exemple précédent, les mots "Titre de la page" et "Contenu" doivent être traduits.

Weblate¶

Nous utilisons Weblate pour la traduction du contenu. Lorsque nous ajoutons une nouvelle traduction, nous utilisons DeepL pour la traduction automatique afin de produire une première série de traductions. En d'autres termes, le contenu que vous allez traduire est généralement déjà traduit par une machine. Nous attendons de vous, en tant que traducteur, que vous révisiez, corrigiez et amélioriez la traduction automatique existante.

Weblate traite tout sur une base chaîne par chaîne. Il regroupe les changements, et toutes les deux heures, il soumettra un commit groupé avec toutes les chaînes qui ont été modifiées dans cet intervalle. Ainsi, il peut s'écouler quelques heures avant que vos changements n'apparaissent sur le site web, mais vous pouvez vous attendre à ce que la mise à jour apparaisse dans un délai de quatre heures.

Si, passé ce délai, vos modifications n'apparaissent toujours pas, la cause probable est une erreur de balisage, entraînant un échec de la compilation des documents pour cette langue. Tout problème de balisage dans une chaîne empêchera la publication de l'ensemble de la traduction. Vous pouvez surveiller la page de compilation de votre langue pour voir si elle a été compilée avec succès. Le lien est formaté de manière similaire à ce lien vers la page de compilation française https://app.readthedocs.org/projects/beewareorg/; remplacez le code de langue par celui de votre langue pour afficher la page de compilation correspondante. Cela vous permettra de voir l'état de la dernière compilation du site. Si la compilation échoue, consultez le journal de compilation et essayez d'identifier la source du problème.