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 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)ページコンテンツ、_meta.ts サイドバーラベル、およびテーマ辞書モジュールを 1 回の sync 実行で翻訳する場合は、features.translateDocs を有効にします。
ページレイアウト
i18n対応のNextra 4は、ソースロケールのMDXをロケールフォルダー配下に保持します (ソースが英語の場合、通常は content/en/ です)。sourceLocale には任意の言語を指定できます。翻訳されたコピーは、兄弟関係にあるロケールフォルダーに書き込まれます。
content/en/index.mdx → content/pt-BR/index.mdx
content/en/guide/getting-started.mdx → content/zh-Hans/guide/getting-started.mdxdocs[] ブロックを1つ設定します:
{
"contentPaths": ["content/en"],
"outputDir": "content",
"docsOutput": {
"style": "nextra",
"docsRoot": "content/en",
"rewriteNextraLinks": true
}
}contentPaths で、sourceLocale で書かれた .mdx のファイルとディレクトリを指定します。その言語は任意です。docsRoot には、content/ 内のソースロケールフォルダーを設定します (たとえば、ソースが英語の場合は content/en です)。
Nextra の 国際化 を設定します。next.config で i18n.locales と defaultLocale を設定し、ai-i18n-tools.config.json の targetLocales をこれらのロケールコードと content/{locale}/ フォルダー名に合わせます。
既存のサイトで i18n を有効にする
英語のみのNextra 4サイトでは、translate-docsが書き込み先を持つ前に、ロケールフォルダー、ルートパラメーター、およびNext.jsのi18n設定が必要です。初回セットアップでは、ウェブサイトまたはドキュメントサイトにi18nを追加のプロンプトを使用します。辞書プロンプトは、同じルートと辞書に対する詳細なフォローアップです。チェックリスト:
- MDXを
content/en/に移動します (英語はコンテンツのルートではなく、ロケールフォルダーです)。 next.config内のi18n.localesとdefaultLocale。app/[lang]/ルート、getPageMap('/${lang}')、および<Layout i18n={…}>。app/_dictionaries/en.tsとget-dictionary.tsを<Layout>、<Navbar>、<Footer>に渡します。nextra/localesを再エクスポートするオプションのproxy.ts(オプションのロケールプロキシを参照)。- それらのロケールコードに合わせた
targetLocales、そしてsync。
テーマ文字列
Nextraテーマの文字列(editLink、検索プレースホルダー、フッターなど)はMarkdownから抽出されません。英語の文字列を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 ファイルを再生成してください。
サンプルプロジェクト
Nextraドキュメントの例 — 英語のソースはcontent/en/にあり、コミットされたpt-BRとzh-Hansのページツリー、インラインの_meta.tsファイル、およびapp/_dictionaries/{locale}.tsがあります。1つのサーバーコンポーネント(app/_components/feedback-links.tsx)は、フラットバンドルルックアップを介してt()を使用し、これによりカスタムシェル文字列を辞書と並べて配置できます。ポート3070でpnpm run devを実行します。
エージェント プロンプト: 辞書とルート
サイトにまだハードコードされたレイアウト文字列があり、content/en/ ツリーがない場合に使用します。これはデフォルトのパス (辞書 + _meta.ts + translate-docs) に従います。t() は導入しません。
辞書とルートのプロンプト
# 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/`.オプション: app/ React (ハイブリッド) 向けの t()
デフォルト: _meta.tsオブジェクトリテラルとapp/_dictionaries/en.tsはtranslate-docsによって翻訳されます。これらのシェル文字列にはt()は不要です。
オプションのハイブリッド: カスタムサーバーコンポーネントは t("source sentence") と translate-ui を呼び出すことができます。文章は sourceLocale で書かれており、これは任意の言語にすることができます。それらの呼び出しに辞書文字列や _meta.ts のタイトルをコピーしないでください。extract は t() 内のリテラルしか認識しないため、ui.sourceRoots にはそれらの呼び出しを含むフォルダーのみをリストアップする必要があります (例では app/_components を使用)。app/_dictionaries は含めません。
changeLanguage を持つモジュールレベルのi18nextシングルトンは、同時リクエストがそれを共有するため、サーバーコンポーネントでは安全ではありません。この例では、代わりにステートレスなルックアップを使用します。getT(lang) はターゲットロケール用に locales/{lang}.json をロードし、ソースルートを空のバンドルとして扱います (英語のリテラルがすでにテキストであるため)。そして ai-i18n-tools/runtime からの interpolateTemplate で補間します。プレースホルダーはASCIIの単語キーを持つ {{name}} です。これは examples/astro-website/src/i18n/t.ts と同じ考え方です。
そのルックアップは複数形を選択しません。plurals: true を必要とするコンポーネントは、クライアントコンポーネントで i18nextの接続 のi18nextパスを使用するか、リクエストごとの createInstance() を使用する必要があります。
ハイブリッド用の設定 (既存のドキュメントブロックの横):
features.translateUIStringsui.sourceRoots—t()呼び出しを含むフォルダーui.stringsJsonui.flatOutputDir
この例の sourceLocale は en-GB で、サイトルートは en です。ステートレスなルックアップでは en ルートにバンドルは不要なため、その不一致は問題になりません。問題になるのは、このコンポーネントをi18nextのブートストラップに切り替えた場合のみです。ブートストラップは sourceLocale によってバンドルをキー付けします。
| コンテンツ | デフォルトのパイプライン | オプションの代替 |
|---|---|---|
| MDX ページ本体 | translate-docs | — |
_meta.ts / _meta.tsx オブジェクトのタイトル | translate-docs | JSX (ハイブリッド) で t() にリファクタリング |
app/ レイアウト、_components/ | nextraDictionaryPath + 辞書 .ts | t() + translate-ui |
examples/nextra-docs の app/_components/feedback-links.tsx と lib/ui-t.ts を参照してください。その例の pnpm run i18n:sync-ui は、ドキュメントのパイプラインに触れることなく、抽出と translate-ui を実行します。
AIエージェントプロンプトの例 (辞書の横に t() を追加する際に、Cursorまたは別のコーディングエージェントにコピーしてください):
ハイブリッドt()プロンプト
# 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 は、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 および 出力レイアウト も参照してください。