Skip to content

Nextra integration ​

Use init -t ui-nextra and docsOutput.style: "nextra" for Nextra 4 documentation sites on Next.js App Router. The preset is an alias for doc-system with an empty localeSubpath and BCP-47 locale folder names preserved (localePathLowercase defaults to false, so folders stay pt-BR, zh-Hans, etc.).

See also Documents, and the runnable examples/nextra-docs demo.

Quick start ​

bash
ai-i18n-tools init -t ui-nextra -P gemini
# 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)

Enable features.translateDocs when you translate page content, _meta.ts sidebar labels, and theme dictionary modules in one sync run.

Page layout ​

Nextra 4 with i18n keeps the source-locale MDX under a locale folder (typically content/en/ when English is the source). sourceLocale can be any language. Translated copies are written to sibling locale folders:

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

Configure one docs[] block:

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

Point contentPaths at the .mdx files and directories written in sourceLocale. That language can be any language. Set docsRoot to the source-locale folder inside content/ (for example content/en when English is the source).

Wire Nextra internationalization: set i18n.locales and defaultLocale in next.config, and keep targetLocales in ai-i18n-tools.config.json aligned with those locale codes and the content/{locale}/ folder names.

Enable i18n in an existing site ​

An English-only Nextra 4 site needs a locale folder, a route param, and Next.js i18n config before translate-docs has anywhere to write. First-time setup uses the prompt on Add i18n to a website or docs site. The dictionary prompt is the detailed follow-up for the same routes and dictionary. Checklist:

  • Move MDX to content/en/ (English is a locale folder, not the content root).
  • i18n.locales and defaultLocale in next.config.
  • An app/[lang]/ route, getPageMap('/${lang}'), and <Layout i18n={…}>.
  • app/_dictionaries/en.ts plus get-dictionary.ts, passed into <Layout>, <Navbar>, and <Footer>.
  • Optional proxy.ts that re-exports nextra/locales (see Optional locale proxy).
  • targetLocales aligned with those locale codes, then sync.

Theme strings ​

Nextra theme strings (editLink, search placeholder, footer, and so on) are not extracted from markdown. Author English strings in a TypeScript dictionary module (for example app/_dictionaries/en.ts) and translate it inside translate-docs:

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

The tool writes app/_dictionaries/{locale}.ts (default template: {dir}/{locale}.ts). Load the per-locale module in app/_dictionaries/get-dictionary.ts and pass translated strings to <Layout>, <Search>, <Footer>, and related theme components.

Do not use json[] for Nextra theme dictionary strings — that pattern is for unrelated app locale bundles only.

Nextra 3+ uses TypeScript _meta.ts / _meta.tsx files for sidebar structure and titles. When docsOutput.style is "nextra", translate-docs automatically collects _meta.ts, _meta.tsx, and _meta.js under docsRoot, translates string literals in the export default { … } meta map, and writes mirrored files under content/{locale}/**.

Recommended pattern: keep English literals inline in content/en/**/_meta.ts (same as swr-site):

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

Optional: override collection with docs[].nextraMetaGlob or restrict translatable property names with docs[].nextraMetaTranslatableKeys (default: title, display, breadcrumb).

Do not hand-author JSON sidecars (i18n/meta.en.json) or thin _meta.ts files that import translated JSON — regenerate locale _meta files with sync / translate-docs when English changes.

Example project ​

examples/nextra-docs — English sources at content/en/, committed pt-BR and zh-Hans page trees, inline _meta.ts files, and app/_dictionaries/{locale}.ts. One server component (app/_components/feedback-links.tsx) uses t() through a flat-bundle lookup so custom shell strings can sit beside the dictionary. Run pnpm run dev on port 3070.

Agent prompt: dictionary and routes ​

Use this when the site still has hardcoded layout strings and no content/en/ tree. It follows the default path (dictionary + _meta.ts + translate-docs). It does not introduce t().

Dictionary and routes prompt
markdown
# Add Nextra 4 i18n with a theme dictionary

## Context

ai-i18n-tools translates Nextra page bodies, `_meta.ts` object literals, and the
theme dictionary module (`nextraDictionaryPath`, usually
`app/_dictionaries/en.ts`) with `translate-docs`. The English sentence in that
dictionary is the source text. Do not translate strings yourself. Reference:
https://github.com/wsj-br/ai-i18n-tools/tree/main/examples/nextra-docs

## Scope

Edit `next.config`, `app/[lang]/layout.tsx`, `app/_dictionaries/en.ts`,
`app/_dictionaries/get-dictionary.ts`, and move MDX under `content/en/`. Skip
`docsRepositoryBase` (a URL). Keep native language names in a `LOCALE_LABELS`
map untranslated (`English`, `Português (Brasil)`). Do not move `_meta.ts`
sidebar labels into the dictionary or into `t()`.

## Call shape

- `next.config`: `i18n.locales` and `defaultLocale`.
- English MDX and `_meta.ts` live under `content/en/`. `getPageMap('/${lang}')`
  loads the matching tree.
- `app/_dictionaries/en.ts` exports the English shell strings (`siteTitle`, `footer`,
  `editLink`, search placeholder, table-of-contents title, last-updated label).
  `get-dictionary.ts` dynamically imports `./${locale}`.
- Pass those fields into `<Layout>`, `<Navbar>`, and `<Footer>`. Set
  `<Layout i18n>` from `LOCALE_LABELS`.
- Config: `features.translateDocs`, `docsOutput.style: "nextra"`,
  `docsRoot: "content/en"`, `nextraDictionaryPath: "app/_dictionaries/en.ts"`.
  `targetLocales` matches `i18n.locales` except the default locale.

## Order

1. Route, config, and dictionary wiring.
2. Move existing MDX into `content/en/` and point `contentPaths` at that folder.
3. Ask the user to run `sync`. Do not write `app/_dictionaries/pt-BR.ts` or
   `content/pt-BR/` by hand.

## Do not

- Do not translate, rename, or reword the English dictionary strings.
- Do not add `t()`, `getRequestConfig`, or a `dictionary.ts` filename. The
  English module is `app/_dictionaries/en.ts`.
- Do not duplicate a string in both the dictionary and a later `t()` call.
- Do not hand-edit generated locale dictionaries or locale `_meta.ts` files.

## Verify

- `pnpm build` passes.
- `/` shows the English dictionary strings. After `sync`, one non-English route
  shows translated shell strings and page titles.
- Sidebar labels come from `content/en/**/_meta.ts`, not from the dictionary.

## Report back

List files changed, each layout string you left untranslated and why (URLs,
native language names), and any MDX you were not sure belonged under
`content/en/`.

Optional: t() for app/ React (hybrid) ​

Default: _meta.ts object literals and app/_dictionaries/en.ts are translated by translate-docs. No t() is required for those shell strings.

Optional hybrid: custom server components can call t("source sentence") and translate-ui. The sentence is written in sourceLocale, which can be any language. Do not copy dictionary strings or _meta.ts titles into those calls. extract only sees literals inside t(), so ui.sourceRoots should list only the folders that contain those calls (the example uses app/_components), not app/_dictionaries.

A module-level i18next singleton with changeLanguage is unsafe in a server component: concurrent requests share it. The example uses a stateless lookup instead. getT(lang) loads locales/{lang}.json for a target locale, treats the source route as an empty bundle (the English literal is already the text), and interpolates with interpolateTemplate from ai-i18n-tools/runtime. Placeholders are {{name}} with ASCII word keys. This is the same idea as examples/astro-website/src/i18n/t.ts.

That lookup does not select plural forms. A component that needs plurals: true should use the i18next path from Wire i18next in a client component, or a per-request createInstance().

Config for the hybrid, beside the existing docs block:

  • features.translateUIStrings
  • ui.sourceRoots — folders that contain t() calls
  • ui.stringsJson
  • ui.flatOutputDir

The example's sourceLocale is en-GB and the site route is en. With the stateless lookup the en route needs no bundle, so that mismatch does not matter. It matters only if you switch this component to the i18next bootstrap, which keys bundles by sourceLocale.

ContentDefault pipelineOptional alternative
MDX page bodiestranslate-docs—
_meta.ts / _meta.tsx object titlestranslate-docsrefactor to t() in JSX (hybrid)
app/ layout, _components/nextraDictionaryPath + dictionary .tst() + translate-ui

See app/_components/feedback-links.tsx and lib/ui-t.ts in examples/nextra-docs. pnpm run i18n:sync-ui in that example runs extract and translate-ui without touching the docs pipeline.

Example AI agent prompt (copy into Cursor or another coding agent when adding t() beside the dictionary):

Hybrid t() prompt
markdown
# Add a stateless t() lookup to a Nextra 4 server component

## Context

MDX pages, `_meta.ts`, and `app/_dictionaries/en.ts` stay on `translate-docs`.
Do not duplicate those strings in `t()`. This task adds `t("source sentence")`
only in custom components that the dictionary does not cover. The literal is the
catalog key and is written in `sourceLocale`, which can be any language. Do not translate any string.

Follow `lib/ui-t.ts` and `app/_components/feedback-links.tsx` in
https://github.com/wsj-br/ai-i18n-tools/tree/main/examples/nextra-docs

## Scope

Edit the named components and `ai-i18n-tools.config.json`. Do not edit
`app/_dictionaries`, `content/**/_meta.ts`, or generated locale trees. Skip
URLs, native language names, and `docsRepositoryBase`.

## Call shape

Create `lib/ui-t.ts`. `getT(lang)` loads `locales/{lang}.json` through a
dynamic-import map for target locales, uses an empty bundle for the source
route, and returns
`(source, vars) => interpolateTemplate(flat[source] ?? source, vars ?? {})` with
`interpolateTemplate` imported from `ai-i18n-tools/runtime`.

Replace hardcoded sentences in the named server components with `t("source sentence")`. The sentence is written in `sourceLocale`, which can be any language.
A placeholder is `t("You are reading {{page}}.", { page })`.

Do not use `getRequestConfig` (that is a next-intl API) and do not call
`changeLanguage` on a shared i18next instance. This lookup does not resolve
plurals. Leave plural copy on the i18next client path.

Set `features.translateUIStrings`, `ui.sourceRoots` to only the folders that
contain `t()` calls, `ui.stringsJson`, and `ui.flatOutputDir`.

## Order

1. Add `lib/ui-t.ts` and the `t()` calls.
2. Set the four `ui` config keys.
3. Run `ai-i18n-tools extract` (or `sync-ui`). Do not hand-write
   `locales/*.json`.

## Do not

- Do not translate, rename, or reword the source sentences.
- Do not put `t()` keys in `app/_dictionaries` or move `_meta.ts` titles into
  `t()`.
- Do not hand-edit `strings.json` or flat locale files.
- Do not change layout or Nextra theme props that already receive dictionary
  strings.

## Verify

- `extract` writes a non-empty catalog containing the new sentences and nothing
  from the dictionary.
- The project build passes.
- The source route still shows the English sentences. After `translate-ui`, one
  non-English route renders the translated component.

## Report back

List files changed, each string you left in the dictionary on purpose, and any
plural or server-concurrency case you did not convert.

Nextra serves locale-prefixed routes via Next.js i18n (/guide/getting-started, /pt-BR/guide/getting-started). In-page links should stay locale-neutral (/guide/getting-started) so Next.js can prefix the active locale automatically.

Enable the built-in normaliser so translate-docs fixes links in every translated file automatically:

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

rewriteNextraLinks defaults to enabled when style is "nextra".

Author in the source localeAfter normaliser
[Guide](content/en/guide/getting-started.mdx)[Guide](/guide/getting-started)
[Guide](../guide/getting-started.mdx)[Guide](/guide/getting-started)
[Demo](https://github.com/org/repo)unchanged (full URL)

Authoring rules

  • Cross-page doc links: use locale-neutral site routes (/guide/…) in English MDX, or content/en/… / relative .mdx paths and let the normaliser rewrite them during sync.
  • Repo files outside the content tree: use full URLs.
  • Do not hand-edit links in content/<locale>/ — regenerate with sync / translate-docs.

Optional locale proxy ​

Nextra provides a locale-detection proxy for i18n sites. Export it from proxy.ts in your project root:

ts
export { proxy } from 'nextra/locales'

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

Site locale codes vs sourceLocale: Nextra and Next.js use short route codes (en, pt-BR, zh-Hans) in next.config, content/{locale}/, and the NEXT_LOCALE cookie. sourceLocale in ai-i18n-tools.config.json can be a BCP-47 tag such as en-GB for translation quality — that tag is not a site route. If the browser cookie or Accept-Language resolves to a tag outside i18n.locales (for example en-GB when only en is configured), Nextra's stock proxy can redirect in a loop. The examples/nextra-docs demo wraps nextra/locales to reset invalid cookies and paths to the default site locale before delegating.

This does not work with output: 'export' static exports. See Nextra i18n docs.

See also Configuration — docsOutput and Output layouts.

Released under the MIT License.