readme-i18n

Présentation de la skill readme-i18n

Ce que fait readme-i18n

readme-i18n est une skill ciblée pour transformer un unique README.md au format GitHub en un ensemble de README multilingues facile à maintenir. Il ne s’agit pas d’un outil de localisation générale d’application. Son rôle principal est de traduire le README source, de créer des fichiers frères comme README.zh.md, de préserver le Markdown et les mécanismes du dépôt, puis d’ajouter ou de normaliser un sélecteur de langue commun sur toutes les variantes.

À qui s’adresse readme-i18n

Cette skill convient aux mainteneurs, aux contributeurs open source et aux agents IA qui travaillent sur la documentation d’un dépôt lorsque l’objectif réel n’est pas seulement de « traduire du texte », mais de « livrer des fichiers README traduits qui fonctionnent toujours sur GitHub ». Si vous tenez à garder cohérents les badges, les liens, les blocs de code, la convention de nommage des fichiers et les sélecteurs de langue, readme-i18n constitue un meilleur point de départ qu’un prompt de traduction générique.

Le vrai besoin auquel répond la skill

La plupart des tentatives de traduction de README échouent à cause de la structure, pas du vocabulaire. Les utilisateurs ont besoin d’un workflow qui :

• traite un fichier comme source unique de vérité
• garde le même ordre de sections
• préserve les commandes, chemins, extraits de code et mécanismes de liens
• met à jour chaque variante linguistique de façon cohérente
• évite les sélecteurs de langue dupliqués ou cassés

C’est là toute la valeur pratique de la readme-i18n skill.

Pourquoi cette skill est différente d’un prompt classique

Le principal différenciateur, c’est la logique de décision. La skill indique à l’agent ce qu’il faut préserver à l’identique, à quel moment demander une clarification unique, comment déduire les conventions à partir des fichiers existants, et comment mettre à jour un sélecteur en place au lieu d’en créer un nouveau. Les références incluses sont particulièrement utiles pour l’adoption, car elles réduisent les tâtonnements habituels autour de l’emplacement du sélecteur et de la gestion sûre du Markdown pendant la traduction.

Comment utiliser la skill readme-i18n

Contexte d’installation de readme-i18n

Installez la skill depuis le dépôt xixu-me/skills dans l’environnement compatible Skills que vous utilisez déjà. Si votre configuration prend en charge l’installation directe depuis GitHub, le schéma le plus courant est :

npx skills add https://github.com/xixu-me/skills --skill readme-i18n

Si votre environnement gère les skills autrement, utilisez l’URL du dépôt https://github.com/xixu-me/skills/tree/main/skills/readme-i18n comme référence source et chargez la skill depuis skills/readme-i18n.

Fichiers à lire avant la première utilisation

Pour cette skill, l’ordre de lecture le plus rapide et le plus rentable est :

1. skills/readme-i18n/SKILL.md
2. skills/readme-i18n/references/language-selector-reference.md
3. skills/readme-i18n/references/preservation-checklist.md

Cet ordre compte. SKILL.md présente le workflow, la référence sur le sélecteur montre la forme et l’emplacement attendus du bloc, et la checklist de préservation précise ce qui doit rester inchangé.

Quelles entrées fournir à readme-i18n

La skill fonctionne au mieux lorsque vous indiquez :

• le chemin du README source, généralement README.md
• la langue source
• la ou les langues cibles
• tout glossaire ou terme à ne pas traduire
• la convention de nommage existante si le dépôt localise déjà ses README

Si vous n’indiquez pas les langues cibles, la skill est conçue pour inspecter d’abord les fichiers déjà traduits, les sélecteurs, les noms de fichiers, les issues ou les conventions du dépôt. Si la langue reste malgré tout ambiguë, elle doit poser une seule question plutôt qu’inventer des cibles.

Les hypothèses par défaut à connaître

Les valeurs par défaut documentées sont pragmatiques et utiles à connaître avant d’exécuter readme-i18n :

• le README.md à la racine est la source de vérité, sauf indication contraire
• la langue source est supposée être l’anglais si ce n’est pas ambigu
• l’ordre des sections doit rester aligné sur la source
• les schémas de nommage multilingues existants doivent être conservés plutôt que remplacés

Ces choix rendent la skill plus sûre pour des dépôts existants qu’une simple demande de traduction sans cadre.

Comment bien formuler un prompt pour readme-i18n

Une demande faible serait : « Traduis mon README en chinois. »

Un prompt de readme-i18n usage plus solide serait :

• traduire README.md de l’anglais vers le chinois simplifié
• créer README.zh.md
• préserver les commandes, chemins, URL de badges, blocs de code et liens relatifs
• ajouter un sélecteur de langue en haut des deux fichiers
• garder un ordre de titres strictement identique
• ne pas traduire le nom du produit AcmeCLI ni les variables d’environnement
• suivre toute convention de nommage existante si elle est détectée

Ce niveau de précision améliore directement la qualité de sortie, car il correspond aux règles de préservation et de sélecteur de la skill.

Exemple de workflow de traduction avec readme-i18n

Un workflow readme-i18n for Translation concret ressemble à ceci :

1. Identifier le README source de vérité.
2. Vérifier si des variantes traduites existent déjà.
3. Détecter la convention de nommage du dépôt et le style actuel du sélecteur.
4. Traduire uniquement le contenu en langue naturelle.
5. Préserver à l’identique le code, les commandes, les URL et les chemins de fichiers.
6. Ajouter ou normaliser un bloc de sélecteur unique près du haut de chaque variante.
7. Vérifier les liens, le formatage et la cohérence entre tous les fichiers.

C’est le bon modèle mental : non pas « traduire du texte », mais « maintenir une famille de README ».

Comment doit fonctionner le sélecteur de langue

Le fichier d’appui le plus utile dans cette skill est la référence sur le sélecteur. Elle recommande un bloc de sélecteur unique près du haut de chaque variante de README, généralement après le titre et le groupe de badges, avec des marqueurs stables :

<!-- README-I18N:START -->
<!-- README-I18N:END -->

Ces marqueurs sont importants, car les exécutions futures peuvent ainsi mettre à jour le sélecteur en place. La langue courante doit être mise en évidence sans lien ; les autres langues doivent pointer vers un lien. Gardez le même ordre des langues dans toutes les variantes.

Ce qui doit être préservé exactement

La checklist de préservation est la partie la plus critique de ce guide readme-i18n pour décider de l’adoption. En pratique, ne traduisez pas :

• le code inline
• les blocs de code délimités
• les commandes, flags, variables d’environnement, chemins
• les URL de badges et leurs paramètres de requête
• les chemins source des images
• la structure des tableaux
• les mécanismes de HTML brut

Traduisez le texte visible, mais préservez les mécanismes qui font réellement fonctionner le README.

Conventions de dépôt respectées par readme-i18n

Si le dépôt utilise déjà une convention de nommage autre que la valeur par défaut :

• README.md
• README.zh.md
• README.es.md

la skill doit conserver cette convention. C’est essentiel pour les dépôts qui ont déjà une localisation partielle, des références CI ou des attentes de contribution liées aux noms de fichiers.

Là où readme-i18n fait gagner le plus de temps

Cette skill est particulièrement utile lorsqu’au moins un de ces freins à l’adoption existe :

• vous devez maintenir plusieurs fichiers README localisés et synchronisés
• le dépôt a déjà un sélecteur de langue désordonné ou dupliqué
• de précédentes traductions ont cassé le Markdown ou les liens
• vous voulez des mises à jour répétables plutôt que des retouches manuelles ponctuelles

Si vous avez seulement besoin d’une traduction privée approximative pour comprendre un README, cette skill apporte probablement plus de processus que nécessaire.

FAQ sur la skill readme-i18n

readme-i18n convient-il aux débutants ?

Oui, si votre objectif est précisément la localisation de README. La skill cadre la tâche avec des entrées claires et des règles de préservation, ce qui est plus simple que d’inventer votre propre workflow de traduction. Les débutants doivent malgré tout relire le résultat, en particulier les cibles de liens, les titres et la cohérence du sélecteur.

Quand utiliser readme-i18n plutôt qu’un prompt de traduction classique ?

Utilisez readme-i18n lorsque le README traduit doit être versionné dans un dépôt. Un prompt classique peut trop traduire, modifier les exemples de code, casser les liens de badges ou oublier la navigation entre fichiers. Cette skill est préférable quand l’exactitude du résultat compte davantage que la vitesse.

readme-i18n est-il réservé aux dépôts GitHub ?

Il est optimisé pour les README de dépôts au format GitHub et pour les conventions Markdown associées. Il peut aussi aider sur d’autres plateformes Git, mais ses hypothèses sont surtout adaptées aux dépôts open source centrés sur README.md, et non aux sites de documentation complets ou aux systèmes de localisation produit.

Est-ce que readme-i18n gère des ensembles complets de documentation ?

Non. Il s’agit d’un workflow centré sur le README. Si vous devez gérer l’i18n d’un site, d’une application ou d’une documentation complète, la readme-i18n skill est trop spécialisée. Sa force est de maintenir de manière cohérente un document d’entrée de dépôt et ses variantes localisées.

Quelles langues peut-on utiliser ?

La skill est agnostique vis-à-vis des langues, à condition que vous indiquiez les cibles ou que le dépôt les rende déjà explicites. Elle évite délibérément d’inventer des langues cibles lorsque le dépôt ne fournit pas assez d’indices.

Est-ce que readme-i18n peut mettre à jour une configuration README multilingue existante ?

Oui, et c’est même l’un de ses meilleurs cas d’usage. Elle est conçue pour inspecter les fichiers traduits et les sélecteurs actuels, préserver les conventions de nommage et normaliser un sélecteur existant plutôt que d’en ajouter un second.

Dans quels cas readme-i18n n’est pas un bon choix ?

Évitez-la si :

• vous voulez seulement une traduction de lecture informelle
• votre documentation se trouve ailleurs que dans le README
• vous avez besoin d’une gestion terminologique sur un vaste corpus documentaire
• votre dépôt ne veut pas de liens de sélecteur de langue dans les fichiers README

Dans ces cas-là, un prompt plus léger ou un workflow de localisation documentaire plus large sera souvent plus adapté.

Comment améliorer la skill readme-i18n

Donner à readme-i18n des contraintes source plus solides

De meilleures entrées produisent de meilleures variantes de README. Incluez :

• le chemin exact du fichier source
• les locales cibles exactes
• les termes à ne jamais traduire
• les autonymes préférés pour les noms de langue
• si les fichiers traduits existants doivent être écrasés ou seulement mis à jour

Cela réduit le mode d’échec le plus courant : une traduction correcte, mais un comportement inadapté au dépôt.

Fournir un glossaire des noms et termes techniques

Si votre README contient des noms de produit, des commandes CLI, des noms de package ou une terminologie métier, listez-les explicitement. readme-i18n essaie déjà de préserver les éléments littéraux, mais un court glossaire améliore la cohérence dans les titres, les descriptions de fonctionnalités et les exemples.

Indiquer clairement à la skill ce qu’elle ne doit pas modifier

L’un des meilleurs moyens d’améliorer readme-i18n usage consiste à poser des limites fermes :

• conserver tous les blocs de code strictement à l’identique
• préserver les liens relatifs
• ne pas renommer les fichiers sauf demande explicite
• ne pas modifier les cibles des badges
• ne pas réordonner les sections

Ces consignes sont étroitement alignées sur la checklist de préservation et évitent des modifications « utiles » en apparence, mais nuisibles en pratique.

Vérifier l’emplacement du sélecteur avant de valider

Un problème de sortie fréquent est un sélecteur de langue maladroit ou dupliqué. Comparez le sélecteur généré avec references/language-selector-reference.md et vérifiez :

• qu’un seul sélecteur existe par fichier
• que son emplacement est cohérent entre les variantes
• que la langue courante est en gras, sans lien
• que les liens pointent vers les vrais noms de fichiers frères

C’est une petite étape de revue qui rapporte beaucoup.

Contrôler les titres localisés et les ancres

Les titres traduits peuvent modifier le comportement des ancres générées sur les plateformes qui dérivent les fragment IDs du texte des titres. La skill vise à préserver la hiérarchie des titres, mais vous devriez quand même tester les liens internes vers les titres après traduction, surtout pour les README longs.

Itérer à partir de la source, pas d’éditions ponctuelles

Pour une maintenance durable, gardez README.md comme source de vérité et relancez readme-i18n à partir des mises à jour de la source, au lieu d’éditer à la main chaque fichier localisé de manière indépendante. Cela permet de conserver dans le temps l’alignement de l’ordre des sections, du contenu du sélecteur et de la terminologie.

Utiliser une vérification côte à côte après le premier passage

Après la première exécution, comparez les fichiers source et cible sur les points suivants :

• même nombre de sections
• même nombre de blocs de code
• mêmes tableaux et même structure de listes
• mêmes images et badges
• liens du sélecteur fonctionnels

Cette vérification détecte les régressions structurelles plus vite qu’une relecture phrase par phrase.

Améliorer les exécutions futures avec des conventions de dépôt explicites

Si votre dépôt suit un schéma multilingue non standard, indiquez-le directement dans le prompt la prochaine fois que vous invoquez readme-i18n. Exemples :

• “Use README.ja.md, not README.jp.md”
• “Keep the existing unmarked selector and normalize it in place”
• “Spanish variant should be README.es-419.md”

La skill devient nettement plus fiable lorsque les conventions du dépôt sont exprimées explicitement au lieu d’être simplement déduites.