Nextra 통합
Next.js App Router에서 Nextra 4 문서 사이트에 init -t ui-nextra 및 docsOutput.style: "nextra"을 사용하세요. 이 사전 설정은 빈 localeSubpath 및 BCP-47 로케일 폴더 이름이 보존된 doc-system의 별칭입니다(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 사이드바 레이블, 테마 사전 모듈을 한 번의 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.mdx하나의 docs[] 블록을 구성하세요:
{
"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, 검색 플레이스홀더, 푸터 등)은 마크다운에서 추출되지 않습니다. 영어 문자열을 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 테마 사전 문자열에 절대 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. 하나의 서버 컴포넌트(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/_dictionaries이 아닌 해당 호출을 포함하는 폴더만 나열해야 합니다(예제에서는 app/_components 사용).
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](/ko/guide/getting-started) |
[Guide](/ko/guide/getting-started.mdx) | [Guide](/ko/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 및 출력 레이아웃도 참조하십시오.