Support multilingue

Si votre documentation doit toucher des utilisateurs dans plusieurs langues, vous pouvez définir des arborescences de navigation distinctes par locale et permettre aux lecteurs de basculer via un menu déroulant dans la barre supérieure.

Configuration

Encapsulez votre navigation dans un tableau languages, chaque langue contenant sa propre structure de navigation :

{
  "navigation": {
    "languages": [
      {
        "language": "en",
        "tabs": [
          {
            "tab": "Documentation",
            "groups": [
              {
                "group": "Getting Started",
                "pages": ["introduction", "quickstart"]
              }
            ]
          }
        ]
      },
      {
        "language": "es",
        "tabs": [
          {
            "tab": "Documentación",
            "groups": [
              {
                "group": "Comenzar",
                "pages": ["es/introduction", "es/quickstart"]
              }
            ]
          }
        ]
      }
    ]
  }
}

Langues prises en charge

Structure des répertoires

Organisez le contenu traduit dans des répertoires préfixés par la langue :

my-docs/
├── docs.json
├── introduction.mdx          # English (default)
├── quickstart.mdx
├── es/
│   ├── introduction.mdx      # Spanish
│   └── quickstart.mdx
├── fr/
│   ├── introduction.mdx      # French
│   └── quickstart.mdx
└── de/
    ├── introduction.mdx      # German
    └── quickstart.mdx

Référencez les pages dans la navigation en utilisant leur chemin complet (avec le préfixe de langue) :

{
  "language": "es",
  "tabs": [
    {
      "tab": "Documentación",
      "groups": [
        {
          "group": "Comenzar",
          "pages": ["es/introduction", "es/quickstart"]
        }
      ]
    }
  ]
}

Paramètres spécifiques à chaque langue

Chaque langue peut avoir sa propre configuration :

{
  "navigation": {
    "languages": [
      {
        "language": "en",
        "banner": {
          "content": "Version 2.0 is now live! See our [changelog](/changelog).",
          "dismissible": true
        },
        "tabs": [...]
      },
      {
        "language": "es",
        "banner": {
          "content": "¡La versión 2.0 está disponible! Ver [registro de cambios](/es/changelog).",
          "dismissible": true
        },
        "tabs": [...]
      }
    ]
  }
}

Traduction des libellés de la barre de navigation

Les liens de la barre supérieure et le bouton CTA principal acceptent un objet labels optionnel avec des traductions par langue. Lorsque le lecteur se trouve sur une URL préfixée (par ex. /fr/...), la traduction correspondante est utilisée ; sinon, le label par défaut s'affiche.

{
  "navbar": {
    "links": [
      {
        "label": "Blog",
        "labels": { "fr": "Blog", "es": "Blog" },
        "href": "/blog"
      },
      {
        "label": "Pricing",
        "labels": { "fr": "Tarifs", "es": "Precios" },
        "href": "/pricing"
      }
    ],
    "primary": {
      "type": "button",
      "label": "Dashboard",
      "labels": { "fr": "Tableau de bord", "es": "Panel" },
      "href": "https://app.example.com"
    }
  }
}

Les libellés intégrés — le bouton Search, le bouton Ask AI et le menu déroulant More — sont traduits automatiquement pour chaque langue prise en charge. Aucune configuration n'est requise.

Langue par défaut

La première langue du tableau est la langue par défaut. Les utilisateurs qui arrivent sur votre documentation voient cette langue en premier. Le sélecteur de langue leur permet de changer.

Structure des URL

Les préfixes de langue apparaissent dans les URL :

Traductions partielles

Vous n'avez pas besoin de traduire chaque page. Si une page n'existe pas dans une langue, les utilisateurs voient un message de repli avec un lien vers la version anglaise.

Pour les pages qui ne doivent pas être traduites (comme la référence API), vous pouvez référencer la même page dans plusieurs langues :

{
  "language": "es",
  "tabs": [
    {
      "tab": "API",
      "groups": [
        {
          "group": "Endpoints",
          "pages": ["api/users", "api/posts"]  // Same as English
        }
      ]
    }
  ]
}

Traduction des specs OpenAPI

Les pages d'endpoint pilotées par OpenAPI (celles comportant une directive frontmatter openapi:) rendent le contenu depuis un fichier de spec YAML ou JSON. Pour traduire le résumé de l'endpoint, les descriptions, les indications de paramètres et les descriptions de champs de schéma, fournissez un fichier de spec spécifique à la langue à côté de votre version anglaise.

Nommage des fichiers

Placez la spec traduite à côté de la source, en insérant le code de langue avant l'extension :

openapi/
├── api.yaml           # English (default)
├── api.fr.yaml        # French
├── api.es.yaml        # Spanish
└── api.zh.yaml        # Simplified Chinese

Aucune configuration ni modification de docs.json n'est requise. Jamdesk résout la spec correspondante au moment du rendu en fonction du préfixe de langue de l'URL. Une page à /fr/api-reference/create-ticket cherche d'abord api.fr.yaml, puis se replie sur api.yaml si aucune traduction n'existe.

Ce qu'il faut traduire dans la spec

Traduisez la prose lisible par un humain. Gardez chaque valeur structurelle identique entre les langues.

Comportement de repli

Si une page est demandée sous une URL localisée mais qu'aucune spec traduite n'existe, Jamdesk rend la spec anglaise dans le shell de page traduite. Les utilisateurs voient un bloc d'endpoint en langue mixte plutôt qu'une erreur 404. Cela correspond au comportement général de traductions partielles pour les pages MDX.

Supprimer une spec spécifique à une langue

La suppression de api.<lang>.yaml provoque le repli de la page sur la spec anglaise au prochain rendu (aucune reconstruction n'est requise). Pour retraduire depuis zéro, supprimez le fichier et régénérez-le. Aucune modification de docs.json n'est nécessaire — la résolution de la spec est purement basée sur le nom de fichier.

Exemple

Source openapi/tickets.yaml :

info:
  title: Tickets API
  description: Manage support tickets.
paths:
  /tickets:
    post:
      summary: Create a ticket
      description: Create a new support ticket.
      operationId: createTicket

Traduction française openapi/tickets.fr.yaml :

info:
  title: API Tickets
  description: Gérez les tickets de support.
paths:
  /tickets:
    post:
      summary: Créer un ticket
      description: Créer un nouveau ticket de support.
      operationId: createTicket

Notez que /tickets, post et createTicket restent identiques. Seule la prose change.

Workflow de traduction

Langues RTL

Les langues de droite à gauche comme l'arabe et l'hébreu sont prises en charge. Jamdesk applique automatiquement le style RTL lorsque ces langues sont actives.

Prochaines étapes