Intégration Nextra

Utilisez init -t ui-nextra et docsOutput.style: "nextra" pour les sites de documentation Nextra 4 sur Next.js App Router. Le préréglage est un alias pour doc-system avec un localeSubpath vide et les noms de dossiers de paramètres régionaux BCP-47 conservés (localePathLowercase est par défaut false, donc les dossiers restent pt-BR, zh-Hans, etc.).

Voir aussi Documents, et la démo exécutable examples/nextra-docs.

Démarrage rapide

bash

ai-i18n-tools init -t ui-nextra [-P <provider>]
# edit ai-i18n-tools.config.json (targetLocales, providers, contentPaths)
pnpm run i18n:sync   # or: ai-i18n-tools sync
pnpm run build       # Next.js build (project-specific script)

Activez features.translateDocs lorsque vous traduisez le contenu des pages, les étiquettes de la barre latérale _meta.ts et les modules de dictionnaire de thème en une seule exécution de sync.

Disposition de la page

Nextra 4 avec i18n conserve le code source MDX anglais dans un dossier de paramètres régionaux (généralement content/en/). Les copies traduites sont écrites dans des dossiers de paramètres régionaux frères :

text

content/en/index.mdx              →  content/pt-BR/index.mdx
content/en/guide/getting-started.mdx  →  content/zh-Hans/guide/getting-started.mdx

Configurez un bloc docs[] :

json

{
  "contentPaths": ["content/en"],
  "outputDir": "content",
  "docsOutput": {
    "style": "nextra",
    "docsRoot": "content/en",
    "rewriteNextraLinks": true
  }
}

Pointez contentPaths vers vos fichiers et répertoires .mdx anglais. Définissez docsRoot sur le dossier de paramètres régionaux anglais dans content/.

Connectez l'internationalisation Nextra : définissez i18n.locales et defaultLocale dans next.config, et maintenez targetLocales dans ai-i18n-tools.config.json aligné avec ces codes de paramètres régionaux et les noms de dossiers content/{locale}/.

Chaînes de thème

Le chrome du thème Nextra (editLink, l'espace réservé à la recherche, le pied de page, etc.) n'est pas extrait du markdown. Rédigez les chaînes anglaises dans un module de dictionnaire TypeScript (par exemple app/_dictionaries/en.ts) et traduisez-le dans translate-docs :

json

{
  "features": {
    "translateDocs": true
  },
  "docs": [
    {
      "contentPaths": ["content/en"],
      "outputDir": "content",
      "nextraDictionaryPath": "app/_dictionaries/en.ts",
      "docsOutput": {
        "style": "nextra",
        "docsRoot": "content/en"
      }
    }
  ]
}

L'outil écrit app/_dictionaries/{locale}.ts (modèle par défaut : {dir}/{locale}.ts). Chargez le module par paramètres régionaux dans app/_dictionaries/get-dictionary.ts et transmettez les chaînes traduites à <Layout>, <Search>, <Footer> et aux composants de thème associés.

N'utilisez pas json[] pour les chaînes du dictionnaire de thème Nextra — ce modèle est uniquement destiné aux bundles de paramètres régionaux d'applications non liés.

Étiquettes de la barre latérale (`_meta.ts`)

Nextra 3+ utilise des fichiers TypeScript _meta.ts / _meta.tsx pour la structure et les titres de la barre latérale. Lorsque docsOutput.style est "nextra", translate-docs collecte automatiquement _meta.ts, _meta.tsx et _meta.js sous docsRoot, traduit les littéraux de chaîne dans la carte méta export default { … } et écrit des fichiers en miroir sous content/{locale}/**.

Modèle recommandé : conservez les littéraux anglais en ligne dans content/en/**/_meta.ts (comme pour swr-site) :

text

content/en/_meta.ts           English sidebar labels (source)
content/pt-BR/_meta.ts        Translated copy (generated by translate-docs)

Facultatif : remplacez la collection par docs[].nextraMetaGlob ou restreignez les noms de propriétés traduisibles avec docs[].nextraMetaTranslatableKeys (par défaut : title, display, breadcrumb).

Ne créez pas manuellement de sidecars JSON (i18n/meta.en.json) ou de fichiers _meta.ts minces qui importent du JSON traduit — régénérez les fichiers _meta de paramètres régionaux avec sync / translate-docs lorsque l'anglais change.

Exemple de projet

examples/nextra-docs — Sources anglais à content/en/, arborescences de pages pt-BR et zh-Hans validées, fichiers _meta.ts en ligne et app/_dictionaries/{locale}.ts. Exécutez pnpm run dev sur le port 3070.

Facultatif : `t()` pour `app/` React (hybride)

Par défaut : les chaînes de littéraux d'objet _meta.ts / _meta.tsx sont traduites à l'intérieur de translate-docs — aucun t() n'est requis.

Hybride facultatif : les équipes peuvent également utiliser t() + translate-ui pour le chrome de mise en page app/, les composants MDX personnalisés ou les étiquettes _meta.tsx qui ne vivent qu'à l'intérieur des corps de composants JSX (au-delà de l'extraction de littéraux d'objet en v1). Cela ne remplace pas translate-meta pour les fichiers méta, sauf si vous refactorisez explicitement les étiquettes de la barre latérale en composants.

Contenu	Pipeline par défaut	Alternative facultative
Corps de page MDX	`translate-docs`	—
Titres d'objet `_meta.ts` / `_meta.tsx`	`translate-docs`	refactoriser en `t()` dans JSX (hybride)
Mise en page `app/`, `_components/`	`nextraDictionaryPath` + dictionnaire `.ts`	`t()` + `translate-ui`

Exemple d'invite d'agent IA (copiez dans Cursor ou un autre agent de codage lors de la migration du chrome de mise en page vers t()) :

markdown

Add i18n to our Nextra 4 app/ layout using ai-i18n-tools translate-ui (optional hybrid).

Context:
- We already translate MDX pages and _meta.ts via translate-docs (default).
- We want t() in app/[lang]/layout.tsx and app/_components/ for labels not covered by nextraDictionaryPath.
- English-as-key: t("Edit this page on GitHub") in source; strings.json + locales/{locale}.json from extract + translate-ui.
- Do not move _meta.ts sidebar labels into t() unless we explicitly ask — translate-docs handles _meta object literals.

Requirements:
1. Wire getRequestConfig / i18n provider for the app router locale param.
2. Replace hard-coded layout strings with t() calls; keep structure and Nextra theme APIs unchanged.
3. Enable features.translateUIStrings, set ui.sourceRoots to app/ (and mdx-components if needed).
4. Do not duplicate dictionary.ts strings that nextraDictionaryPath already translates — pick one approach per string.

After editing: run extract, translate-ui (or sync), verify en + one target locale in dev.

Conventions de lien

Nextra sert des routes préfixées par le locale via Next.js i18n (/guide/getting-started, /pt-BR/guide/getting-started). Les liens internes à la page doivent rester neutres par rapport au locale (/guide/getting-started) afin que Next.js puisse préfixer automatiquement le locale actif.

Activez le normaliseur intégré pour que translate-docs corrige automatiquement les liens dans chaque fichier traduit :

json

"docsOutput": {
  "style": "nextra",
  "docsRoot": "content/en",
  "rewriteNextraLinks": true
}

rewriteNextraLinks est activé par défaut lorsque style est "nextra".

Auteur en source anglais	Après normalisation
`[Guide](content/en/guide/getting-started.mdx)`	`[Guide](/fr/guide/getting-started)`
`[Guide](/fr/guide/getting-started.mdx)`	`[Guide](/fr/guide/getting-started)`
`[Demo](https://github.com/org/repo)`	inchangé (URL complète)

Règles de rédaction

Liens de documentation inter-pages : utilisez des routes de site neutres par rapport au locale (/guide/…) dans MDX anglais, ou des chemins content/en/… / .mdx relatifs et laissez le normalisateur les réécrire pendant sync.
Fichiers de dépôt en dehors de l'arborescence de contenu : utilisez des URL complètes.
Ne modifiez pas manuellement les liens dans content/<locale>/ — régénérez avec sync / translate-docs.

Proxy de locale facultatif

Nextra fournit un proxy de détection de locale pour les sites i18n. Exportez-le depuis proxy.ts à la racine de votre projet :

export { proxy } from 'nextra/locales'

export const config = {
  matcher: [
    '/((?!api|_next/static|_next/image|favicon.ico|icon.svg|apple-icon.png|manifest|_pagefind).*)',
  ],
}

Codes de locale de site vs sourceLocale : Nextra et Next.js utilisent des codes de route courts (en, pt-BR, zh-Hans) dans next.config, content/{locale}/ et le cookie NEXT_LOCALE. sourceLocale dans ai-i18n-tools.config.json peut être une balise BCP-47 telle que en-GB pour la qualité de la traduction — cette balise n'est pas une route de site. Si le cookie du navigateur ou Accept-Language se résout en une balise en dehors de i18n.locales (par exemple en-GB lorsque seul en est configuré), le proxy standard de Nextra peut rediriger en boucle. La démo examples/nextra-docs enveloppe nextra/locales pour réinitialiser les cookies et chemins invalides au locale de site par défaut avant de déléguer.

Cela ne fonctionne pas avec les exportations statiques output: 'export'. Voir Nextra i18n docs.

Voir aussi Configuration — docsOutput et Output layouts.

Chaînes d'interface utilisateur

Documents

Intégrations

Images et captures d'écran

Traduction SVG

Tableau de bord de traduction

Intégration Nextra

Démarrage rapide

Disposition de la page

Chaînes de thème

Étiquettes de la barre latérale (`_meta.ts`)

Exemple de projet

Facultatif : `t()` pour `app/` React (hybride)

Conventions de lien

Proxy de locale facultatif

Chaînes d'interface utilisateur

Documents

Intégration Nextra ​

Démarrage rapide ​

Disposition de la page ​

Chaînes de thème ​

Étiquettes de la barre latérale (_meta.ts) ​

Exemple de projet ​

Facultatif : t() pour app/ React (hybride) ​

Conventions de lien ​

Proxy de locale facultatif ​

Intégration Nextra

Démarrage rapide

Disposition de la page

Chaînes de thème

Étiquettes de la barre latérale (`_meta.ts`)

Exemple de projet

Facultatif : `t()` pour `app/` React (hybride)

Conventions de lien

Proxy de locale facultatif