Guide de traduction / How to contribute to the translation

Pour contribuer à la traduction ou ajouter des langues, c'est relativement simple.

Nous utilisons la bibliothèque Lingui, et nous avons globalement 5 ou 6 types de supports de traduction.

Les textes de l'interface

Paragraphes, boutons, liens : tous ces éléments sont dans le HTML ou plus précisément dans notre cas, dans le JSX, le HTML de React, la bibliothèque qui fait tourner la moitié du net.

Ils sont traduits via les fichiers .po dans locales/[lang]/messages.po. C'est un format standard, gettext. On n'a pas encore branché d'interface en ligne participative, elles sont chères ou lourdes à installer.

Si vous utilisez une LLM pour faire ou contribuer à traduire un messages.po, pas de souci mais vous devez la citer dans le message de commit.

En tant que traducteur, ne vous étonnez pas ne pas trouver certaines clefs de traduction dans les fichiers .po : il faut à la main (ou via une LLM) ajouter des trucs dans le code pour chaque élément à traduire. C'est en cours, ça va être fait progressivement.

Car il faut englober tous les textes à traduire dans les balises HTML par <Trans> et {t}.

<button onClick={()=> alert('plop')}>Y aller</button>

devient

import { Trans } from '@lingui/react/macros'
<button ...><Trans>Let's go</Trans></button>

Example avec t

import { t } from '@lingui/react/macros'
<img alt={t`Un chat domestique qui empêche un oiseau d'aller picorer des vers de terre`}/>

La langue de base est le français et le restera jusqu'à nouvel ordre.

Tous ces textes sont extraits grâce à la commande bun lingui:extract dans les fichiers .po. Cette commande les marque comme "à traduire". Si vous n'êtes pas développeur ni curieux, vous pouvez ignorer cette étape et vous concentrer uniquement sur les textes déjà marqués comme à traduire.

Note : parfois il faut aussi utiliser bun run lingui:extract --clean pour nettoyer les traductions périmées ou mettre à jour les lignes des traductions.

Pour aider à traduire, j'utilise aider. Il a l'avantage de bien bosser et de faire le commit automatiquement en y inscrivant la version du modèle, chose qui est requise par notre guide de contribution.

MISTRAL_API_KEY=MA_CLEF_MISTRAL aider --model mistral/mistral-large-2512 --no-gitignore locales/*/messages.po
"Fill the missing translations in the messages.po files. Only the missing translations, don't touch the others."

Les messages automatiquement traduits doivent être commentés par la ligne # auto-translated by MODÈLE en début de bloc. C'est important, pour que les traducteurs humains puissent le savoir et l'améliorer.

Ensuite, un modèle ne doit pas sauf exception changer une traduction humaine.

Le fond de carte

Il est traduit automatiquement lors de la création des cartes. C'est ici qu'on ajoute des nouvelles langues. Ensuite côté client c'est pas trivial de bien traduire, cf ce ticket.

Le blog

Fichiers contenus dans /article

Tous les articles peuvent être traduits. Certains le sont en anglais. C'est simple : créer une nouvelle entrée dans /articles/ en respectant le format des autres, et en ajoutant deux attributs à l'en-tête YAML : lang: (par exemple it) et original: qui donne le slug de l'article en français qui est la source de cette traduction.

Variante : les pages qui utilisent notre moteur de blog mais qui apparaissent sur des chemins dédiés, comme cartes.app/a-propos. Il faut simplement ajouter un a-propos.[lang].mdx.

D'autres fichiers mdx ailleurs

• components/explanations.mdx
• components/news/news.yaml

Les attributs OSM

Ils sont gérés dans le projet commun à OSM "id-tagging-schema", sauf pour nos améliorations des traductions françaises qu'on a codé ici. Il faudra les remonter dans le dépôt commun.

Les catégories et autres fichiers YAML

Les catégories sont un élément très important de cartes.app. Elles permettent les filtres rapides en icônes, mais aussi le répertoire complet de la centaine de catégories ! Et puis aussi la suggestion automatique de "bar" quand on cherche "bière", grâce à leurs dictionnaires.

En plus de ça, elles construisent l'annuaire, essentiel pour les moteurs de recherche. Et puis elles permettent aussi d'afficher un icône bière sur les fiches lieux des bars. Bref, c'est important.

Pour les traduire, il faut ajouter un fichier categories.yaml dans locales/[lang]/. Regardez le fichier anglais pour comprendre ce qu'il doit comporter, ou lisez le commentaire d'en-tête ici, et celui-ci spécifique à la traduction. Ce script createLanguageCategoriesTemplate.ts est actionné via bun run translate-categories et permet de créer le fichier de traduction sur la base de la source française, qu'il n'y aura plus qu'à traduire. Le script est idempotent : il peut être utilisé également pour mettre à jour les traductions après une évolution des catégories source françaises.

Le fichier translation.md cité plus haut est aussi une instruction qui devrait permettre à une LLM de gérer cette traduction.

Par exemple via aider et Mistral.

MISTRAL_API_KEY=MA_CLEF aider --model mistral/mistral-large-2512 --no-gitignore locales/*/categories.yaml components/categories/categories.yaml components/categories/translation.md
# Puis l'instruction suivante : 
# Please fill locales/br/categories.yaml with translations. Read the comment in components/categories/translation.md to understand what's to be done and follow the instructions in the comment
>  

D'autres éléments divers

• Ajouter les jours de la semaine dans le fichier app/osm/edit/ohEncoder.ts

• Traduire les éléments cartographiques de l'interface qui sont gérés par MapLibre

Pour l'instant, c'est traduit en français, et pour toutes les autres langues ça passe à l'anglais ou autre selon locales/preferences.yaml

À ajouter ici.