mintlify__docs/fr/guides/internationalization.mdx

---
title: "Internationalisation"
description: "Configurez une documentation multilingue pour atteindre un public mondial."
keywords: ["internationalisation", "i18n", "multilingue", "traductions", "localisation", "sélecteur de langue"]
---

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.

<div id="file-structure">
  ## Structure des fichiers
</div>

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](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes). Placez les fichiers traduits dans ces répertoires en respectant la même structure que pour votre langue par défaut.

<Expandable title="codes de langue pris en charge">
  * `ar` - arabe
  * `cs` - tchèque
  * `zh` ou `zh-Hans` - chinois (simplifié)
  * `zh-Hant` - chinois (traditionnel)
  * `de` - allemand
  * `en` - anglais
  * `es` - espagnol
  * `fr` - français
  * `he` - hébreu
  * `hi` - hindi
  * `id` - indonésien
  * `it` - italien
  * `jp` - japonais
  * `ko` - coréen
  * `lv` - letton
  * `nl` - néerlandais
  * `no` - norvégien
  * `pl` - polonais
  * `pt` ou `pt-BR` - portugais
  * `ro` - roumain
  * `ru` - russe
  * `sv` - suédois
  * `tr` - turc
  * `ua` - ukrainien
  * `uz` - ouzbek
  * `vi` - vietnamien
</Expandable>

```text 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
```

<Tip>
  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.
</Tip>


<div id="configure-the-language-switcher">
  ## Configurer le sélecteur de langue
</div>

Pour ajouter un sélecteur de langue à votre documentation, configurez le tableau `languages` dans la propriété `navigation` de votre fichier `docs.json`.

```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.


<div id="set-default-language">
  ### Définir la langue par défaut
</div>

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` :

```json docs.json
{
  "navigation": {
    "languages": [
      {
        "language": "es",
        "groups": [...]
      },
      {
        "language": "en",
        "groups": [...]
      }
    ]
  }
}
```

Vous pouvez également utiliser la propriété `default` pour modifier l’ordre :

```json docs.json
{
  "navigation": {
    "languages": [
      {
        "language": "en",
        "groups": [...]
      },
      {
        "language": "es",
        "default": true,
        "groups": [...]
      }
    ]
  }
}
```


<div id="single-language-documentation">
  ### Documentation en une seule langue
</div>

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 :

```json 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.

<Tip>
  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.
</Tip>


<div id="global-navigation">
  ### Navigation globale
</div>

Pour ajouter des éléments de navigation globaux qui apparaissent dans toutes les langues, configurez l&#39;objet `global` dans la propriété `navigation` de votre fichier `docs.json`.

```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
    ]
  }
}
```


<div id="maintain-translations">
  ## Conserver les traductions
</div>

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

<div id="translation-workflow">
  ### Processus de traduction
</div>

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.

<div id="automated-translations">
  ### Traductions automatisées
</div>

Pour des solutions de traduction automatique, [contactez l'équipe commerciale de Mintlify](mailto:gtm@mintlify.com).

<div id="external-translation-providers">
  ### Prestataires de traduction externes
</div>

Si vous travaillez avec vos propres prestataires de traduction ou traducteurs locaux, vous pouvez intégrer leur workflow à votre documentation Mintlify à l’aide de GitHub Actions ou d’outils CI/CD similaires.

1. **Exporter le contenu source** : extrayez les fichiers MDX à traduire.
2. **Envoyer aux traducteurs** : transmettez les fichiers à votre prestataire de traduction.
3. **Recevoir les traductions** : récupérez les fichiers MDX traduits.
4. **Importer et déployer** : ajoutez les fichiers traduits aux répertoires de langue et mettez à jour la navigation.

Ce workflow GitHub Actions exporte automatiquement le contenu anglais modifié pour traduction lorsque des PR sont fusionnées dans `main`.

```yaml .github/workflows/export-for-translation.yml
name: Export content for translation

on:
  push:
    branches: [main]
    paths:
      - '*.mdx'
      - '!es/**'
      - '!fr/**'
      - '!zh/**'

jobs:
  export:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 2

      - name: Get changed files
        id: changed
        run: |
          echo "files=$(git diff --name-only HEAD~1 HEAD -- '*.mdx' ':!es/' ':!fr/' ':!zh/' | tr '\n' ' ')" >> $GITHUB_OUTPUT

      - name: Create translation package
        if: steps.changed.outputs.files != ''
        run: |
          for file in ${{ steps.changed.outputs.files }}; do
            mkdir -p "translation-export/$(dirname "$file")"
            cp "$file" "translation-export/$file"
          done

      - name: Upload translation package
        if: steps.changed.outputs.files != ''
        uses: actions/upload-artifact@v4
        with:
          name: translation-export-${{ github.sha }}
          path: translation-export/
```

Ce workflow GitHub Actions valide et importe le contenu traduit lorsqu’il est ajouté via une PR.

```yaml .github/workflows/import-translations.yml
name: Import translations

on:
  pull_request:
    paths:
      - 'es/**'
      - 'fr/**'
      - 'zh/**'

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Validate frontmatter
        run: |
          for file in $(git diff --name-only origin/main...HEAD -- '*.mdx'); do
            if ! head -1 "$file" | grep -q '^---$'; then
              echo "Erreur : $file ne contient pas de frontmatter"
              exit 1
            fi
          done

      - name: Check file structure
        run: |
          # Vérifier que les fichiers traduits correspondent à la structure source
          for lang in es fr zh; do
            if [ -d "$lang" ]; then
              for file in $(find "$lang" -name '*.mdx'); do
                source_file="${file#*/}"
                if [ ! -f "$source_file" ]; then
                  echo "Avertissement : $file n'a pas de source anglaise à $source_file"
                fi
              done
            fi
          done
```

**Bonnes pratiques pour les flux de traduction externes**

* **Préserver le frontmatter** : assurez-vous que les traducteurs conservent le frontmatter YAML intact et ne traduisent que les valeurs de `title` et `description`.
* **Protéger les code blocks** : indiquez à vos prestataires que les code blocks ne doivent pas être traduits.
* **Utiliser la mémoire de traduction** : fournissez des glossaires contenant les termes techniques qui doivent rester en anglais ou avoir une traduction spécifique.
* **Automatiser la validation** : utilisez des vérifications CI pour valider la syntaxe MDX et le frontmatter avant d’intégrer les traductions.
* **Contrôle de version** : suivez la version source de chaque traduction afin d’identifier le contenu obsolète.


<div id="images-and-media">
  ### Images et médias
</div>

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.

```mdx es/index.mdx
![Capture d'écran du Dashboard](/images/fr/dashboard.png)
```


<div id="seo-for-multi-language-sites">
  ## SEO pour les sites multilingues
</div>

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

<div id="page-metadata">
  ### Metadata de la page
</div>

Incluez les metadata traduites dans le frontmatter de chaque fichier :

```mdx fr/index.mdx
---
title: "Commencer"
description: "Apprenez à commencer avec notre produit."
keywords: ["démarrage", "tutoriel", "guide"]
---
```


<div id="best-practices">
  ## Bonnes pratiques
</div>

<div id="date-and-number-formats">
  ### Formats de date et de nombre
</div>

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.

<div id="maintain-consistency">
  ### Maintenir la cohérence
</div>

- 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.

<div id="layout-differences">
  ### Différences de mise en page
</div>

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.

<div id="character-encoding">
  ### Encodage des caractères
</div>

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.