Support multilingue

Si votre documentation doit s'adresser à des utilisateurs parlant plusieurs langues, vous pouvez définir des arborescences de navigation distinctes par locale et permettre aux lecteurs de changer de langue 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 à l'aide de 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 à la langue

Chaque langue peut avoir sa propre configuration :

{
  "navigation": {
    "languages": [
      {
        "language": "en",
        "tabs": [...]
      },
      {
        "language": "es",
        "tabs": [...]
      }
    ]
  }
}

Traduire les libellés de la barre de navigation

Les liens de la barre de navigation supérieure et le CTA principal acceptent un objet labels optionnel contenant des surcharges par langue. Lorsque le lecteur se trouve sur une URL préfixée par une langue (par exemple /fr/...), la surcharge correspondante est utilisée ; sinon, le label par défaut est affiché.

{
  "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 chaînes d'interface intégrées (le bouton Search, le bouton Ask AI et le menu déroulant More des onglets) sont traduites automatiquement pour chaque langue prise en charge. Vous n'avez pas besoin de les configurer.

Langue par défaut

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

Structure des URL

Les préfixes de langue apparaissent dans les URL :

Routage automatique de la langue

Par défaut, tout le monde arrive sur votre langue par défaut et doit changer manuellement. Activez localization.autoRedirect pour rediriger directement les nouveaux visiteurs vers leur propre langue :

{
  "localization": {
    "autoRedirect": true
  }
}

Un visiteur dont le navigateur demande le français obtient /fr au lieu de /. Sa langue est mémorisée pendant un an : il n'est donc mis en correspondance qu'une seule fois, et s'il choisit une langue dans le sélecteur, ce choix l'emporte par la suite.

Seule la racine de votre site est jamais redirigée. Tout le reste est laissé exactement tel que le visiteur l'a demandé :

• Une URL de langue s'ouvre toujours dans cette langue. /fr/guides/authentication — ou simplement /fr — sert le français à tout le monde, quelle que soit la demande du navigateur. Quelqu'un a choisi cette URL, donc un lien que vous collez dans un ticket ou un résultat de recherche ouvre la même page pour la personne qui clique dessus.
• Les liens profonds ne sont jamais redirigés. /guides/authentication sert cette page à tout le monde.
• Les robots d'indexation ne sont jamais redirigés. Google et les autres robots continuent de voir votre langue par défaut à la racine, et vos balises hreflang continuent de décider ce qui est indexé.
• Cela n'invente jamais de langue. Si le navigateur du visiteur demande une langue que vous ne publiez pas, il ne se passe rien : il reste sur votre racine par défaut.

llms.txt pour chaque langue

Chaque langue que vous publiez dispose de son propre index llms.txt et de son propre fichier de contenu complet, afin qu'un outil d'IA puisse lire votre documentation dans une langue sans charger les autres :

La racine docs.example.com/llms.txt sert le même fichier que /en/llms.txt. La racine docs.example.com/llms-full.txt contient toujours toutes les langues. Une langue obtient ses propres fichiers dès qu'elle possède au moins une page. Sites multilingues →

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 toutes les langues :

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

Traduire les spécifications OpenAPI

Les pages d'endpoint pilotées par OpenAPI (celles qui comportent une directive de frontmatter openapi:) affichent du contenu à partir d'un fichier de spécification YAML ou JSON. Pour traduire le résumé de l'endpoint, les descriptions, les indications de paramètres et les descriptions des champs de schéma, fournissez un fichier de spécification spécifique à la langue à côté de votre fichier anglais.

Nommage des fichiers

Placez la spécification 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 aucune modification de docs.json n'est nécessaire. Jamdesk résout la spécification correspondante au moment du rendu, en fonction du préfixe de langue de l'URL. Une page à /fr/api-reference/create-ticket recherche d'abord api.fr.yaml, puis se rabat sur api.yaml si aucune traduction n'existe.

Que traduire dans la spécification

Traduisez le texte destiné aux humains. Conservez chaque valeur structurelle identique dans toutes les langues.

Comportement de repli

Si une page est demandée sous une URL localisée mais qu'aucune spécification traduite n'existe, Jamdesk affiche la spécification anglaise à l'intérieur de la coquille de la page traduite. Les utilisateurs voient un bloc de endpoint dans une langue mixte plutôt qu'une erreur 404. Cela correspond au comportement plus général des traductions partielles pour les pages MDX.

Supprimer une spécification spécifique à une langue

La suppression de api.<lang>.yaml fait que la page se rabat sur la spécification anglaise dès le prochain rendu (aucune reconstruction n'est nécessaire). 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 spécification repose uniquement 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

Remarquez que /tickets, post et createTicket restent identiques. Seul le texte change.

Processus de traduction

Langues RTL

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

Et ensuite ?