Comment traduire des documents techniques sans casser le code

TABLE OF CONTENTS

La documentation technique est impitoyable : une seule clôture de code cassée, un espace réservé ou une ancre peut casser les builds, embrouiller les lecteurs ou provoquer des échecs de copier-coller. Ce guide vous offre un flux de travail répétable et sécurisé pour traduire des documents techniques en toute confiance, tout en gardant le code intact et les documents prêts à être livrés.

Pour qui : rédacteurs techniques, défenseurs des développeurs et traducteurs travaillant sur des documents pour développeurs, des guides API et du contenu de type README.

En bref :

Comprendre ce qui ne doit jamais être traduit (code, clés, jetons)
Préserver la syntaxe que les outils analysent (clôtures, accolades, ancres)
Valider les données structurées et les liens après les modifications
Utiliser l’automatisation pour détecter les problèmes avant la publication

Préparation avant la traduction

Inventorier les types de contenu

Markdown (titres, liens, tableaux), blocs de code, code en ligne
Données structurées : extraits JSON/YAML/TOML et fichiers de configuration
Captures d’écran, diagrammes et visuels intégrés

Définir les jetons non traduisibles

Chemins de fichiers, noms de paquets, imports, noms d’API, drapeaux CLI, variables d’environnement
Espaces réservés et variables : {count}, %s, $HOME, {{token}}
Noms de fichiers et extensions : config.yaml, .env, .md, .json

Établir des garde-fous de cohérence

Glossaire/termbase pour les termes de domaine et les noms de produits
Guide de style : ton, formalité, ponctuation, casse, règles de titre
Stratégie d’ancrage/slug par locale (stable vs localisé)

Mettre en place une validation sécurisée

Build de staging pour valider Markdown/liens après chaque lot
Analyseurs/lint pour JSON/YAML/TOML
Vérificateur de liens et validateur d’ancre dans CI

Principales mesures de sauvegarde

Ne pas traduire le code, les identifiants, les clés, les noms de fichiers, les variables d’environnement ou les drapeaux.
Préserver la ponctuation et la syntaxe que les outils analysent (guillemets inversés, accolades, pipes).
Conserver les espaces significatifs : indentation pour le code et structure de liste.
Utiliser des blocs de code clôturés avec une balise de langue de manière cohérente (js, bash, etc.).
Préférer les notes du traducteur plutôt que de “corriger” la logique du code—signaler les problèmes aux mainteneurs à la place.

Blocs de code et code en ligne

Gardez les délimitations de code, les indices de langue et le contenu intacts. Traduisez uniquement les commentaires et les chaînes lisibles par l’homme si nécessaire.

Exemple—sûr vs non sûr :

// SÛR : Seul le commentaire est localisé
// Obtient un jeton utilisateur
import { getToken } from "@acme/sdk";
const token = await getToken();

// NON SÛR : Ne pas traduire les identifiants/importations/noms de paquets
// import { obtenirJeton } from "@acme/sdk"; // ❌

Le code en ligne doit rester tel quel :

Bien : « Exécutez npm install -g acme-cli puis acme login. »
Mal : « Exécutez npm install -g acme-cli puis acme connexion. » ❌

Validez la capacité de copier-coller : Si un lecteur copie un extrait, il doit fonctionner comme dans la source.

Espaces réservés et format de message ICU

Conservez les espaces réservés exactement, y compris l’espacement et la ponctuation autour d’eux.

# Ne modifiez pas les jetons ou l'espacement
echo "Traitement de {count} fichiers"   # ✅
echo "Traitement de { count } fichiers" # ❌ ajoute des espaces à l'intérieur des accolades

Exemple ICU :

{count, plural,
  =0 {Pas de messages}
  one {# message}
  other {# messages}
}

Ne changez pas les clés (count, one, other).
Traduisez uniquement les parties lisibles par l’homme (« message », « messages »).
N’introduisez ni ne supprimez de catégories de pluriel sans directives du produit.

Liens, ancres et slugs

Gardez la syntaxe des liens Markdown et la stratégie de résolution cohérentes.

[Lisez le guide API](/api/getting-started)  
[Voir la section de configuration](#configuration)

Traduisez le texte du lien si nécessaire ; soyez prudent avec les URL et les ancres.
Ancres : soit gardez des ancres stables entre les locales, soit générez des ancres par locale et mettez à jour les références en conséquence.
Vérifiez que les chemins relatifs et les ancres de hachage se résolvent toujours après la traduction.
Ne traduisez pas les extensions de fichiers ou les paramètres de requête.

Données structurées (JSON/YAML/TOML)

Traduisez uniquement les valeurs—jamais les clés, types ou structures. Re-analysez toujours après modification.

JSON :

{
  "title": "Guide de l'utilisateur",
  "cta": "Commencer",
  "limits": { "max": 5, "unit": "requêtes/seconde" }
}

Les clés comme title, cta, limits, max doivent rester inchangées.
Les nombres, booléens et nulls restent sous forme de types, pas de mots.

YAML (regardez les scalaires pliés) :

note: >
  Les lignes sont pliées en un seul paragraphe.
  Gardez l'indentation et les marqueurs intacts.

Préservez les guillemets, échappements, indentations et virgules finales (le cas échéant).

Noms de fichiers, CLI et API

Ne traduisez pas les noms de fichiers, noms de paquets, points de terminaison ou drapeaux CLI.
Gardez la sensibilité à la casse exactement comme dans la source (par exemple, --DryRun vs --dry-run).
Maintenez les commandes textuellement ; ajoutez des annotations si des différences spécifiques à la langue existent.

# Correct
kubectl get pods --namespace default

# Incorrect (drapeau traduit) ❌
kubectl get pods --nom-espace defaut

Pièges du Markdown

Tableaux : gardez les pipes et l’alignement ; ne cassez pas les colonnes.

| Option | Description           |
|-------:|-----------------------|
|   -v   | Sortie verbeuse       |
|   -q   | Mode silencieux       |

Admonitions/notes : conservez les marqueurs utilisés par votre outil.
HTML en ligne : évitez de toucher aux balises/attributs.
Notes de bas de page : gardez les identifiants et l’ordre.
Guillemets intelligents : préférez les guillemets droits dans les contextes de code.

Visuels et Accessibilité

Localisez le texte alternatif pour le sens, pas le contenu pixel.
Préférez les captures d’écran indépendantes de la langue (mettez en évidence l’interface utilisateur, pas la langue), ou fournissez des ensembles par langue.
Gardez les fichiers sources de diagrammes (par exemple, Mermaid) synchronisés entre les langues.
Évitez le texte intégré dans les images ; externalisez les légendes et étiquettes.

SEO et Métadonnées

Traduisez les titres, descriptions et en-têtes en utilisant des mots-clés appropriés à la langue.
Gardez les URL canoniques et hreflang cohérents avec les règles du site.
Ne traduisez pas les clés meta/property ou les clés JSON‑LD.
Alignez les slugs avec votre stratégie d’ancrage pour éviter les erreurs 404.

Flux de travail et Automatisation

Utilisez un flux de travail CAT/LLM qui préserve les segments de code et les balises.
Verrouillez la terminologie avec un glossaire et une liste de termes à ne pas traduire.
Ajoutez des hooks de pré-commit pour analyser le Markdown et valider le JSON/YAML.
Exécutez un vérificateur de liens et un validateur d’ancrage sur chaque PR.
Regroupez les modifications en petits morceaux révisables et suivez les différences.

Outils suggérés (à adapter à votre pile) :

Analyse du Markdown et vérification des liens dans CI
Étape d’analyse JSON/YAML pour détecter les régressions de syntaxe
Packs Regex pour analyser les espaces réservés et les formats numériques

QA et Validation

Exécutez ces vérifications avant la fusion :

Construisez le site pour détecter les problèmes de syntaxe : pnpm build
Vérifications de type/contenu (collections de contenu Astro) : pnpm astro check
Prévisualisez et testez les pages clés : pnpm preview
Validez que les exemples de code se compilent ou s’exécutent (le cas échéant)
Exécutez un vérificateur de liens et d’ancrages ; corrigez les 404 ou les hachages cassés

Pièges Courants

Traduire par accident des clés/espaces réservés.
Casser les clôtures de code ou les tuyaux de table.
Localiser les chemins de fichiers, les drapeaux ou les noms d’API.
Modifier les titres sans mettre à jour les liens d’ancrage.
Introduire des guillemets typographiques dans le code ou le JSON.

Annexe : Listes de Vérification Rapides

Pré-vol (5 éléments)

Glossaire et liste de termes à ne pas traduire prêts
Jetons/espaces réservés définis et protégés
Stratégie d’ancrage/slug confirmée
Cibles de lien mappées (interne vs externe)
Construction de mise en scène disponible

Sécurité des exemples de code (5 éléments)

Clôtures et indices de langue intacts
Identifiants/importations intacts ; commentaires uniquement localisés
Espaces réservés et citations préservés
Test de copier-coller réussi
Extraits obsolètes signalés aux mainteneurs

Données structurées (5 éléments)

Clés et types intacts
Citations/échappements/indentation préservés
Les nombres et booléens restent en tant que types
Analyseur/linter passe localement
Différences examinées pour les changements de clés accidentels

Lecture connexe