Passer au contenu principal
L’internationalisation (i18n) est le processus qui consiste à concevoir un logiciel ou du contenu pour fonctionner avec différentes langues et différents paramètres régionaux. Ce guide explique comment structurer les fichiers, configurer la navigation et maintenir les traductions efficacement afin que vous puissiez aider vos utilisateurs à accéder à votre documentation dans leur langue préférée et améliorer votre portée à l’international.

​
Structure des fichiers

Organisez le contenu traduit dans des répertoires propres à chaque langue afin que votre documentation reste facile à maintenir et pour structurer votre navigation par langue. Créez un répertoire séparé pour chaque langue en utilisant les codes de langue ISO 639-1. Placez les fichiers traduits dans ces répertoires en respectant la même structure que pour votre langue par défaut.
Example file structure
docs/
├── index.mdx                    # anglais (par défaut)
├── quickstart.mdx
├── fr/
│   ├── index.mdx               # French
│   ├── quickstart.mdx
├── es/
│   ├── index.mdx               # Spanish
│   ├── quickstart.mdx
└── zh/
    ├── index.mdx               # Chinese
    └── quickstart.mdx
Conservez les mêmes noms de fichiers et la même structure de répertoires dans toutes les langues. Cela facilite la maintenance des traductions et l’identification du contenu manquant.

​
Configurer le sélecteur de langue

Pour ajouter un sélecteur de langue à votre documentation, configurez le tableau languages dans la propriété navigation de votre fichier docs.json.
docs.json
{
  "navigation": {
    "languages": [
      {
        "language": "en",
        "groups": [
          {
            "group": "Premiers pas",
            "pages": ["index", "quickstart"]
          }
        ]
      },
      {
        "language": "es",
        "groups": [
          {
            "group": "Comenzando",
            "pages": ["es/index", "es/quickstart"]
          }
        ]
      }
    ]
  }
}
Chaque entrée de langue dans le tableau languages nécessite :
  • language : code de langue ISO 639-1
  • Une structure de navigation complète
  • Les chemins d’accès aux fichiers traduits
La structure de navigation peut différer selon les langues pour s’adapter aux besoins de contenu propres à chacune.

​
Définir la langue par défaut

La première langue du tableau languages est automatiquement utilisée comme langue par défaut. Pour définir une autre langue comme langue par défaut, réorganisez le tableau ou ajoutez la propriété default :
docs.json
{
  "navigation": {
    "languages": [
      {
        "language": "es",
        "groups": [...]
      },
      {
        "language": "en",
        "groups": [...]
      }
    ]
  }
}
Vous pouvez également utiliser la propriété default pour modifier l’ordre :
docs.json
{
  "navigation": {
    "languages": [
      {
        "language": "en",
        "groups": [...]
      },
      {
        "language": "es",
        "default": true,
        "groups": [...]
      }
    ]
  }
}

​
Documentation en une seule langue

Si vous ne souhaitez proposer qu’une seule langue sans sélecteur de langue, supprimez le champ languages de votre configuration de navigation. Définissez ensuite directement votre structure de navigation :
docs.json
{
  "navigation": {
    "tabs": [
      {
        "tab": "Documentation",
        "groups": [
          {
            "group": "Premiers pas",
            "pages": ["index", "quickstart"]
          }
        ]
      }
    ]
  }
}
Cela affiche votre documentation dans une seule langue, sans l’interface du sélecteur de langue.
Traduisez les libellés de navigation, comme les noms de groupes ou d’onglets, afin de les faire correspondre à la langue du contenu. Cela crée une expérience entièrement localisée pour vos utilisateurs.
Pour ajouter des éléments de navigation globaux qui apparaissent dans toutes les langues, configurez l’objet global dans la propriété navigation de votre fichier docs.json.
docs.json
{
  "navigation": {
    "global": {
      "anchors": [
        {
          "anchor": "Documentation",
          "href": "https://example.com/docs"
        },
        {
          "anchor": "Blog",
          "href": "https://example.com/blog"
        }
      ]
    },
    "languages": [
      // Navigation spécifique à chaque langue
    ]
  }
}

​
Conserver les traductions

Veillez à ce que vos traductions restent exactes et synchronisées avec votre contenu source.

​
Processus de traduction

  1. Mettez à jour le contenu source dans votre langue principale.
  2. Identifiez le contenu modifié.
  3. Traduisez le contenu modifié.
  4. Relisez les traductions pour en vérifier l’exactitude.
  5. Mettez à jour les fichiers traduits.
  6. Vérifiez que la navigation et les liens fonctionnent.

​
Traductions automatisées

Pour des solutions de traduction automatique, contactez l’équipe commerciale de Mintlify.

​
Images et médias

Stockez les images traduites dans des répertoires propres à chaque langue. 
images/
├── dashboard.png          # Version anglaise
├── fr/
│   └── dashboard.png     # French version
└── es/
    └── dashboard.png     # Spanish version
Référencez les images à l’aide de chemins relatifs dans vos contenus traduits.
es/index.mdx
![Capture d'écran du Dashboard](/images/fr/dashboard.png)

​
SEO pour les sites multilingues

Optimisez chaque version dans chaque langue pour les moteurs de recherche.

​
Metadata de la page

Incluez les metadata traduites dans le frontmatter de chaque fichier :
fr/index.mdx
---
title: "Commencer"
description: "Apprenez à commencer avec notre produit."
keywords: ["démarrage", "tutoriel", "guide"]
---

​
Bonnes pratiques

​
Formats de date et de nombre

Tenez compte des formats propres à chaque langue pour les dates et les nombres.
  • Formats de date : MM/DD/YYYY vs DD/MM/YYYY
  • Formats de nombres : 1,000.00 vs 1.000,00
  • Symboles monétaires : $100.00 vs 100,00€
Incluez des exemples dans le format approprié pour chaque langue ou utilisez des formats universellement compréhensibles.

​
Maintenir la cohérence

  • Assurez une parité de contenu entre toutes les langues afin que chaque utilisateur bénéficie de la même qualité d’information.
  • Créez un glossaire de traduction pour les termes techniques.
  • Conservez la même structure de contenu dans toutes les langues.
  • Alignez le ton et le style sur ceux de votre contenu source.
  • Utilisez des branches Git pour gérer le travail de traduction séparément des mises à jour du contenu principal.

​
Différences de mise en page

Certaines langues nécessitent plus ou moins d’espace que l’anglais. Testez votre contenu traduit sur différentes tailles d’écran pour vous assurer que :
  • La navigation s’affiche correctement.
  • Les code blocks ne débordent pas.
  • Les tableaux et autres éléments de texte mis en forme restent lisibles.
  • Les images se redimensionnent correctement.

​
Encodage des caractères

Assurez-vous que votre environnement de développement et votre pipeline de déploiement prennent en charge l’UTF-8 afin d’afficher correctement tous les caractères dans les langues utilisant différents alphabets et caractères spéciaux.