Nextra の統合

Next.js App Router 上の Nextra 4 ドキュメントサイトには、init -t ui-nextra と docsOutput.style: "nextra" を使用します。このプリセットは、空の doc-system と BCP-47 ロケールフォルダー名が保持された localeSubpath のエイリアスです (localePathLowercase はデフォルトで false になるため、フォルダーは pt-BR、zh-Hans などになります)。

ドキュメント と、実行可能な examples/nextra-docs デモも参照してください。

クイックスタート

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)

ページコンテンツ、_meta.ts サイドバーラベル、およびテーマ辞書モジュールを 1 回の sync 実行で翻訳する場合は、features.translateDocs を有効にします。

ページレイアウト

i18n を使用する Nextra 4 では、英語のソース MDX をロケールフォルダー内 (通常は content/en/) に保持します。翻訳されたコピーは、兄弟ロケールフォルダーに書き込まれます。

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

docs[] ブロックを1つ設定します：

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

contentPaths を英語の .mdx ファイルとディレクトリに向けます。docsRoot を content/ 内の英語ロケールフォルダーに設定します。

Nextra の 国際化 を設定します。next.config で i18n.locales と defaultLocale を設定し、ai-i18n-tools.config.json の targetLocales をこれらのロケールコードと content/{locale}/ フォルダー名に合わせます。

テーマ文字列

Nextra テーマのクローム (editLink、検索プレースホルダー、フッターなど) はマークダウンから抽出されません。英語の文字列を TypeScript 辞書モジュール (例: app/_dictionaries/en.ts) で作成し、translate-docs 内で翻訳します。

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

このツールは app/_dictionaries/{locale}.ts (デフォルトテンプレート: {dir}/{locale}.ts) を書き込みます。app/_dictionaries/get-dictionary.ts でロケールごとのモジュールをロードし、翻訳された文字列を <Layout>、<Search>、<Footer>、および関連するテーマコンポーネントに渡します。

Nextra テーマ辞書文字列には Nextra テーマ辞書文字列には json[] を使用しないでください。このパターンは、関連性のないアプリロケールバンドル専用です。

サイドバーラベル (_meta.ts)

Nextra 3 以降では、サイドバーの構造とタイトルに TypeScript _meta.ts / _meta.tsx ファイルを使用します。docsOutput.style が "nextra" の場合、translate-docs は docsRoot の下の _meta.ts、_meta.tsx、および _meta.js を自動的に収集し、export default { … } メタマップ内の文字列リテラルを翻訳し、content/{locale}/** の下にミラーリングされたファイルを書き込みます。

推奨パターン: 英語のリテラルを content/en/**/_meta.ts にインラインで保持します (swr-site と同じ)。

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

オプション: docs[].nextraMetaGlob でコレクションをオーバーライドするか、docs[].nextraMetaTranslatableKeys で翻訳可能なプロパティ名を制限します (デフォルト: title、display、breadcrumb)。

JSON サイドカー (i18n/meta.en.json) や、翻訳された JSON をインポートする薄い _meta.ts ファイルを手動で作成しないでください。英語が変更された場合は、sync / translate-docs でロケール _meta ファイルを再生成してください。

サンプルプロジェクト

examples/nextra-docs — content/en/ の英語ソース、コミットされた pt-BR および zh-Hans ページツリー、インライン _meta.ts ファイル、および app/_dictionaries/{locale}.ts。ポート 3070 で pnpm run dev を実行します。

オプション: app/ React (ハイブリッド) 向けの t()

デフォルト: _meta.ts / _meta.tsx オブジェクトリテラル文字列は translate-meta 内で翻訳されます — t() は不要です。

オプションのハイブリッド: チームは、app/ レイアウトのクローム、カスタム MDX コンポーネント、または JSX コンポーネント本体内のみに存在する _meta.tsx ラベル (v1 のオブジェクトリテラル抽出を超える) のために、追加で t() + translate-ui を使用できます。これは、サイドバーラベルをコンポーネントに明示的にリファクタリングしない限り、メタファイル用の translate-meta を置き換えるものではありません。

コンテンツ	デフォルトのパイプライン	オプションの代替
MDX ページ本体	translate-docs	—
_meta.ts / _meta.tsx オブジェクトのタイトル	translate-docs	JSX (ハイブリッド) で t() にリファクタリング
app/ レイアウト、_components/	nextraDictionaryPath + 辞書 .ts	t() + translate-ui

AI エージェントプロンプトの例 (レイアウトクロームを t() に移行する際に Cursor または別のコーディングエージェントにコピー):

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.

リンクの表記規則

Nextra は、Next.js i18n (/guide/getting-started、/pt-BR/guide/getting-started) を介してロケールプレフィックス付きルートを提供します。ページ内リンクはロケールに依存しないようにするべきです (/guide/getting-started)。そうすることで、Next.js がアクティブなロケールを自動的にプレフィックスできます。

組み込みのノーマライザーを有効にすると、translate-docsがすべての翻訳ファイルのリンクを自動的に修正します:

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

style が "nextra" の場合、rewriteNextraLinks はデフォルトで有効になります。

英語ソースで作成	正規化後
[Guide](content/en/guide/getting-started.mdx)	[Guide](/ja/guide/getting-started)
[Guide](/ja/guide/getting-started.mdx)	[Guide](/ja/guide/getting-started)
[Demo](https://github.com/org/repo)	変更なし (完全な URL)

執筆ルール

• ページ間のドキュメントリンク: 英語の MDX では ロケールに依存しないサイトルート (/guide/…) を使用するか、content/en/… / 相対 .mdx パスを使用し、sync の間に正規化ツールで書き換えさせます。
• コンテンツツリー外のリポジトリファイル: 完全な URL を使用します。
• content/<locale>/ のリンクは手動で編集しないでください — sync / translate-docs で再生成してください。

オプションのロケールプロキシ

Nextra は、i18n サイト用のロケール検出プロキシを提供します。プロジェクトルートの proxy.ts からエクスポートします。

export { proxy } from 'nextra/locales'

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

サイトロケールコードと sourceLocale: Nextra と Next.js は、next.config、content/{locale}/、および NEXT_LOCALE クッキーで短いルートコード (en、pt-BR、zh-Hans) を使用します。ai-i18n-tools.config.json の sourceLocale は、翻訳品質のために en-GB のような BCP-47 タグにすることができます — そのタグはサイトルートではありません。ブラウザのクッキーまたは Accept-Language が i18n.locales 外のタグ (たとえば、en のみが設定されている場合の en-GB) に解決される場合、Nextra の標準プロキシはループでリダイレクトする可能性があります。examples/nextra-docs デモは、無効なクッキーとパスをデフォルトのサイトロケールにリセットしてから委任するために nextra/locales をラップします。

これは output: 'export' 静的エクスポートでは機能しません。Nextra i18n ドキュメント を参照してください。

設定 — docsOutput および 出力レイアウト も参照してください。