mikaellolbatera159-stack/localizations

Localiser le contenu dans les locales données

Une compétence qui localise le contenu dans les locales cibles.

Fonctionnement

La compétence prend un contenu d'entrée ainsi qu'une liste de locales cibles. Elle traduit ensuite le contenu dans chaque locale spécifiée, produisant des versions localisées pour chacune.

Structure du contenu

.
└── docs/                         ← contenu de l'atelier (source + sorties localisées)
    ├── README.md                 ← page d'accueil (source ; slug : index)
    ├── <category>/               ← catégorie d'atelier en anglais
    │   ├── README.md             ← page d'accueil de catégorie (source ; slug : <category>)
    │   └── <workshop>/
    │       ├── README.md         ← page d'accueil de l'atelier (source ; slug : <category>/<workshop>)
    │       └── *.md
    ├── _images/                  ← ressources partagées (non localisées)
    └── <locale>/             ← sorties localisées, enfants directs de docs/
        ├── README.md         ← page d'accueil de la locale (slug : <locale>)
        └── <category>/
            ├── README.md         ← page d'accueil localisée de la catégorie (slug : <locale>/<category>)
            └── <workshop>/
                ├── README.md     ← page d'accueil localisée de l'atelier (slug : <locale>/<category>/<workshop>)
                └── *.md

Contenu d'entrée

Voici le contenu pris en compte pour la localisation :

• Tous les fichiers Markdown en anglais situés sous docs/ et ses sous-répertoires — la page d'accueil du site (docs/README.md), les pages d'accueil des catégories, et les leçons d'atelier (docs/<category>/<workshop>/**/*.md).

Ne pas traiter _images/ (ressources partagées) ni les répertoires racine de locale configurés comme source d'entrée.

Les fichiers déjà sous docs/<locale>/ sont des sorties, pas des entrées — ne jamais traiter les répertoires racine de locale configurés comme contenu source à localiser de nouveau.

Locales cibles

Les locales cibles sont définies dans le répertoire rules sous forme de fichiers markdown inclus dans cette compétence (rules/ko-kr.md, par exemple). Pour déterminer les locales à traiter, listez les fichiers dans rules/ : chaque fichier <locale>.md correspond exactement à une locale cible prise en charge. Chaque locale possède son propre ensemble de règles et de directives pour la traduction, garantissant que le contenu localisé est adapté au public cible.

Les identifiants de locale utilisent des minuscules avec un trait d'union (par exemple, ko-kr). Il s'agit de la casse canonique pour le nom du fichier de règles et le répertoire de sortie dans cette compétence ; gardez-les cohérents.

Contenu de sortie

Tout le contenu d'atelier localisé est stocké directement sous le répertoire docs/ à la racine du dépôt, chaque locale ayant son propre sous-répertoire. Par exemple, le contenu coréen est stocké dans docs/ko-kr/.

Les répertoires de locale doivent être des enfants directs de docs/ afin que Starlight (configuré dans website/astro.config.mjs) les reconnaisse et affiche son sélecteur de langue. N'ajoutez pas de répertoire intermédiaire localizations/.

Processus de localisation

Il existe trois cas de figure pour la localisation. Pour déterminer le cas applicable, comparez l'arborescence source avec l'arborescence existante docs/<locale>/, et utilisez l'historique git des fichiers sources pour détecter les modifications :

• Original existant, pas de version localisée pour la locale : Créez un nouveau document localisé.
• Original et version localisée existent tous les deux : Comparez l'arborescence source avec docs/<locale>/, puis exécutez git diff (ou git log) sur le fichier source pour identifier ce qui a changé depuis la dernière production de la version localisée. Mettez à jour uniquement les sections affectées du document localisé ; ne retraduisez pas inutilement les sections inchangées.
• Version localisée existante, mais l'original a été supprimé : Supprimez le document localisé orphelin (et nettoyez les sous-répertoires de locale désormais vides).

Le processus s'effectue en deux passes. Dans un premier temps, le contenu est analysé pour identifier les phrases clés et le contexte. Ensuite, l'agent translator réalise la localisation initiale, suivie d'une passe de révision et d'affinage par l'agent evaluator pour garantir qualité et cohérence.

Les « agents » translator et evaluator sont des rôles/personas, pas des outils externes. Si aucun sous-agent dédié n'est disponible, exécutez-les comme des personas séquentiels : adoptez d'abord le rôle de traducteur pour produire un brouillon, puis adoptez le rôle d'évaluateur pour critiquer et affiner ce brouillon en fonction des règles de la locale. Répétez la boucle d'affinage jusqu'à ce que les critères de l'évaluateur soient satisfaits.

Préservation du Markdown et du formatage

Quelle que soit la locale, les éléments suivants doivent être préservés exactement et non traduits :

• Les clés du frontmatter YAML (traduisez uniquement les valeurs lorsque c'est approprié, par exemple un title). Exception — la clé slug sur les pages d'accueil (README.md) : le site achemine chaque page d'accueil de dossier via son slug, donc une page d'accueil localisée doit porter un slug préfixé par la locale plutôt que le slug anglais. Réécrivez-le : une racine de locale (docs/<locale>/README.md) utilise slug: <locale>, une page d'accueil de catégorie localisée utilise slug: <locale>/<category>, et une page d'accueil d'atelier localisée utilise slug: <locale>/<category>/<workshop>. Ne copiez jamais un slug anglais de page d'accueil tel quel dans un fichier localisé car cela entrerait en conflit avec la route anglaise.
• Le code entre délimiteurs et en ligne, y compris les noms de variables, de fonctions et de commandes.
• Les URL et les cibles de liens externes.
• Les balises HTML, la structure Markdown, les tableaux et les marqueurs d'admonition.

Traduisez le texte en langage humain, y compris les commentaires dans les blocs de code lorsqu'ils sont explicatifs (selon les règles de la locale). Maintenez l'ordre des titres et la structure du document stables.

Les ancres des titres suivent le texte localisé. Lorsqu'un titre est traduit, son ancre/slug auto-généré change avec lui — c'est normal. L'exigence est que les liens d'ancrage au sein du même document continuent de fonctionner : chaque fois que vous traduisez un titre, mettez à jour chaque lien dans la page qui le cible (](#...)) pour utiliser le nouveau slug du titre localisé. Ne laissez pas un lien pointant vers le slug anglais original une fois le titre traduit, et ne conservez pas une ancre anglaise qui ne correspond plus à son titre. Les ancres pointant vers des fichiers non localisés (ou des URL externes) conservent leur cible d'origine.

Les chemins d'images et de ressources pointent vers les ressources originales sauf si une ressource localisée existe. Comme les fichiers localisés se trouvent sous docs/<locale>/, réécrivez les chemins relatifs à la source si nécessaire pour qu'ils pointent toujours vers la ressource partagée (par exemple, une leçon à docs/<locale>/real-world-development/app/2-foo.md utilise ../../../_images/x.png pour atteindre docs/_images/). Ne pointez vers une ressource localisée que si une image traduite correspondante existe effectivement sous l'arborescence de la locale. Dans tous les cas, le lien doit pointer vers un fichier réel.

Agent traducteur

Utilisez l'agent translator pour effectuer la localisation. Il doit suivre les règles et directives définies pour chaque document de locale cible dans le répertoire rules.

Agent évaluateur

Utilisez l'agent evaluator pour évaluer la qualité du contenu localisé. L'évaluateur vérifie l'exactitude, la pertinence culturelle et la qualité globale, en suivant les règles et directives définies pour la locale cible dans le répertoire rules.

L'évaluateur note le document localisé par rapport à la grille d'évaluation de l'évaluateur de la locale (définie dans le fichier rules/<locale>.md). La grille utilise deux niveaux : Tier A (critères d'échec stricts) qui doivent obtenir 5, et Tier B (critères notés de 1 à 5) qui doivent obtenir 4 ou 5. Un document est validé uniquement lorsque chaque critère applicable de Tier A obtient 5 et chaque critère applicable de Tier B obtient ≥ 4. Si un critère n'est pas atteint, renvoyez le document au traducteur avec des notes spécifiques et relancez la boucle traduction → évaluation jusqu'à réussite, en escaladant vers un humain après le nombre maximal d'itérations défini dans la grille.

À FAIRE et À NE PAS FAIRE

• À faire : effectuer la localisation uniquement pour les locales cibles définies dans le répertoire rules (un fichier <locale>.md par locale prise en charge). Ne pas localiser dans des locales non prises en charge.
• À faire : préserver la structure Markdown, le code, les cibles de liens/URL externes et les clés du frontmatter exactement (voir Préservation du Markdown et du formatage).
• À faire : laisser les ancres des titres suivre le texte localisé, et mettre à jour les liens d'ancrage du même document pour correspondre aux nouveaux slugs afin qu'ils continuent de fonctionner (voir Préservation du Markdown et du formatage).
• À faire : faire pointer les chemins d'images et de ressources vers les ressources originales (en réécrivant le chemin relatif si nécessaire pour qu'il soit résolu depuis docs/<locale>/), sauf si une ressource localisée correspondante existe (voir Préservation du Markdown et du formatage).
• À faire : refléter la structure des répertoires sources sous docs/<locale>/.
• À ne pas faire : traiter les répertoires racine de locale configurés comme source d'entrée.
• À ne pas faire : réorganiser ou restructurer le contenu ; maintenir les titres et leur ordre stables.
• À ne pas faire : traduire le code, les commandes ou les identifiants ; ne traduire que le texte explicatif et les commentaires de code.