Localiser du contenu statique

Associez les documents et catalogues traduits aux fichiers utilisés par votre site ou votre moteur de rendu, puis vérifiez la structure, les liens et le résultat livré.

L’arborescence source de votre site relie déjà les articles aux routes, aux métadonnées, à la navigation et à un moteur de rendu. Ajoutez les fichiers traduits là où ce système peut les charger. Le premier résultat concret : une page complète dans la langue cible, accessible à la route prévue, avec des liens fonctionnels et les mêmes exemples de code que la source.

Inventorier les fichiers selon le système qui les utilise #

Séparez les documents longs des catalogues structurés et des ressources spécialisées. Markdown, MDX et Markdoc nécessitent un moteur de rendu et un schéma. Les catalogues JSON, YAML, TypeScript et PHP nécessitent un chargeur. PO et XLIFF s’intègrent à leurs propres systèmes de messages. SRT relève d’un workflow de médias synchronisés.

Choisissez une source représentative de chaque groupe, puis identifiez son chemin de sortie et le chargeur qui l’utilisera. Gardez les fichiers cibles générés hors des motifs de sélection des sources. Préservez les identifiants des documents, les URL, les exemples de code, les clés des catalogues et les attributs des composants dont les valeurs déterminent le comportement.

Consultez Formats pour sélectionner le gestionnaire adapté. Le YAML standard diffère du YAML dont la clé racine est une langue et du YAML OpenAPI. .xml ne permet pas d’identifier automatiquement une ressource Android. Une extension commune ne garantit pas qu’un gestionnaire comprend la structure de votre document.

Respecter la convention de répertoires du site #

Voici les choix d’organisation à vérifier en fonction du chargeur de votre projet :

SitePoints à établir avant la traduction
DocusaurusQuels documents sources deviennent des fichiers sous i18n/<locale>/docusaurus-plugin-content-docs/current/, et quels documents versionnés ou chaînes du thème ont des entrées distinctes.
NextraSi la configuration installée charge des pages par langue, des dictionnaires ou une autre arborescence de contenu ; associez chaque entrée séparément.
HugoQuels fichiers sous content/<locale>/ sont des traductions d’un même contenu et comment les liens entre langues sont résolus.
AstroQuelles collections de contenu propres à chaque langue et quels dictionnaires d’interface alimentent chaque route.
VitePressQuel préfixe de répertoire par langue et quelle configuration de navigation génèrent les pages traduites.
MkDocsQuel plugin i18n et quelle organisation des documents par langue utilise le projet installé.

Dans cet exemple Docusaurus, les documents sources se trouvent sous docs/. Installez et liez la CLI depuis la racine du projet :

sh
npm install --global @lingo.dev/cli
lingo login
lingo init --source en --targets es --files 'docs/**/*.md' --yes
lingo link

Conservez les identifiants de l’organisation et du moteur de localisation dans .lingo/config.json. Comme ces chemins sources ne contiennent aucune langue, remplacez l’entrée du fichier par un modèle de sortie explicite :

json
{
  "pattern": "docs/**/*.md",
  "sourceRoot": "docs",
  "targetPath": "i18n/[locale]/docusaurus-plugin-content-docs/current/[path]"
}

Pour docs/setup/install.md, [path] devient setup/install.md : les fichiers en espagnol sont donc placés dans i18n/es/docusaurus-plugin-content-docs/current/setup/install.md. Vérifiez que le plugin et la version installés utilisent bien ce répertoire. Configuration explique la validation des modèles et les règles de collision.

Choisir avec soin les champs visibles du document à traduire #

Pour Markdown, sélectionnez les champs de métadonnées visibles par les lecteurs, comme le titre et la description. Laissez les métadonnées d’identité et de publication inchangées. Pour MDX et Markdoc, identifiez aussi les propriétés des composants destinées aux lecteurs, comme le titre d’un encadré. Les propriétés qui déterminent le comportement et les noms des composants relèvent du schéma de l’application.

Utilisez le gestionnaire adapté sans supposer que tous les fichiers de la famille Markdown sont interchangeables. Un document Markdoc enregistré sous .md nécessite un format markdoc explicite pour être traité comme du Markdoc. Consultez Markdown, MDX et Markdoc pour connaître les limites de sélection et de reconstruction. Conservez les blocs de code délimités comme éléments de vérification exécutables ; traduisez les explications qui les entourent plutôt que de modifier les commandes.

Lancez un remplissage rétroactif des fichiers manquants :

sh
lingo push --backfill-missing --wait

Une fois l’opération terminée, compilez le site et ouvrez la route cible générée. Vérifiez le titre, la description, le corps du texte, les composants personnalisés, le bloc de code et un lien. Si les identifiants des titres sont dérivés du texte, testez explicitement les liens vers les fragments traduits. Même une URL préservée doit pointer vers une destination existante. Le guide Markdoc avec Next.js donne un exemple de chargement propre à une langue.

Respecter les contrats des catalogues structurés #

Traduisez les valeurs textuelles des catalogues JSON et YAML génériques tout en protégeant les identifiants, les points de terminaison et les autres données non linguistiques à l’aide des contrôles des clés du gestionnaire. Définissez explicitement format: "yaml" pour le YAML générique dans la configuration des sources de la CLI actuelle : déduire le format de l’extension ne suffit pas à autoriser l’envoi d’une source YAML non configurée. Utilisez yaml-root-key lorsque la langue est la clé racine, et yaml-openapi lorsque la structure est celle d’un document OpenAPI. Limitez TypeScript et PHP aux formes de catalogue prises en charge ; traduire un fichier ne permet pas d’évaluer du code source arbitraire en toute sécurité.

Pour PO, conservez les identifiants des messages, le contexte, la structure des pluriels et l’étape de compilation utilisée par le système de destination. Pour XLIFF, préservez la structure source/cible et les espaces réservés de la variante prise en charge. Vérifiez l’importation ou la compilation dans le système qui utilise réellement ces fichiers, sans vous limiter à l’existence d’un fichier de sortie.

Les fichiers .txt en texte brut, comme les descriptions destinées aux boutiques d’applications, sont traduits ligne par ligne en conservant les lignes du fichier source. Incluez .txt dans le motif de sélection des fichiers, comme dans metadata/en/*.txt, ou définissez "format": "txt" : un motif général tel que docs/en/**/* ne les sélectionne pas. Consultez Texte brut. Un tableau CSV comportant une colonne par langue est traduit directement dans le fichier : incluez .csv dans le motif ou définissez "format": "csv", comme l’explique la section CSV. La CLI actuelle ne propose pas les formats « un fichier CSV par langue », WebVTT ou Java .properties comme formats configurables. La référence des formats de la CLI v0 s’adresse aux utilisateurs qui ont déjà installé ces anciens workflows ; ses commandes et sa configuration sont spécifiques à cette version. Appuyez-vous sur la référence de migration pour choisir une approche prise en charge sans écarter ces ressources sans avertissement.

Vérifier les sous-titres avec le média #

Pour SRT, traduisez le texte des sous-titres et comparez leurs indices et leur synchronisation à la source. Visionnez des scènes représentatives avec les sous-titres cibles. Vérifiez la longueur du texte à lire, les sauts de ligne, le contexte des locuteurs et les balises de mise en forme dans le lecteur réellement utilisé. Des horodatages préservés ne garantissent pas qu’un sous-titre traduit peut être lu dans le temps imparti. Consultez SubRip pour connaître le contrat du fichier ; ne le remplacez pas par WebVTT sous prétexte que les deux sont des formats de sous-titres.

Passer à l’échelle à partir d’un circuit de livraison éprouvé #

Conservez ensemble la configuration, les sources, les traductions cibles acceptées et le Lockfile de la CLI. Après avoir modifié un paragraphe, utilisez lingo push --wait pour traiter les changements courants, puis comparez ce paragraphe et une section inchangée dans la traduction cible. Gardez la source précédente associée à sa traduction cible ; une réorganisation de la structure des documents peut rendre la réutilisation ambiguë. Un motif positionnel suit une logique différente de planification par périmètre. Utilisez le workflow d’estimation avant une retraduction à grande échelle, en considérant les estimations comme des informations de planification, et non comme des devis.

Si les corrections locales des traductions cibles nécessitent une protection contre les divergences, soumettez sans --wait et examinez lingo pull --dry-run avant la récupération ; la réécriture directe après attente ne comporte pas ce contrôle. Suivez Préserver les traductions relues.

Choisissez la GitHub App ou les recettes CI une fois qu’un groupe se compile correctement. Conservez dans ce cycle la compilation du site, la validation du schéma, la vérification des liens et la relecture du contenu ; lingo check ne garantit pas que le document est complet. Chaque mise à jour doit laisser une page cible lisible et une révision de la source sur laquelle l’équipe pourra s’appuyer pour la modification suivante.