Skip to content

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 데모도 참조하세요.

빠른 시작 ​

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)

페이지 콘텐츠, _meta.ts 사이드바 레이블, 테마 사전 모듈을 한 번의 sync 실행으로 번역할 때 features.translateDocs을 활성화하세요.

페이지 레이아웃 ​

i18n이 적용된 Nextra 4는 소스 로케일 MDX를 로케일 폴더 아래에 유지합니다(소스가 영어인 경우 일반적으로 content/en/). sourceLocale은 모든 언어가 될 수 있습니다. 번역된 사본은 형제 로케일 폴더에 작성됩니다.

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

하나의 docs[] 블록을 구성하세요:

json
{
  "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 내에서 번역합니다.

json
{
  "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와 동일):

text
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()은 도입하지 않습니다.

사전 및 라우트 프롬프트
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/`.

선택 사항: 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.translateUIStrings
  • ui.sourceRoots — t() 호출을 포함하는 폴더
  • ui.stringsJson
  • ui.flatOutputDir

예제의 sourceLocale은 en-GB이고 사이트 라우트는 en입니다. 상태 비저장 조회를 사용하면 en 라우트에 번들이 필요하지 않으므로 이러한 불일치는 중요하지 않습니다. 이 컴포넌트를 i18next 부트스트랩으로 전환하는 경우에만 중요하며, 이 부트스트랩은 sourceLocale를 기준으로 번들에 키를 지정합니다.

콘텐츠기본 파이프라인선택적 대안
MDX 페이지 본문translate-docs—
_meta.ts / _meta.tsx 객체 제목translate-docsJSX에서 t()로 리팩터링 (하이브리드)
app/ 레이아웃, _components/nextraDictionaryPath + 사전 .tst() + 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() 프롬프트
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는 Next.js i18n (/guide/getting-started, /pt-BR/guide/getting-started)를 통해 로케일 접두사가 붙은 경로를 제공합니다. 페이지 내 링크는 로케일 중립을 유지해야 합니다 (/guide/getting-started). 그래야 Next.js가 활성 로케일을 자동으로 접두사로 붙일 수 있습니다.

내장된 정규화 도구를 활성화하여 translate-docs가 모든 번역된 파일의 링크를 자동으로 수정하도록 하세요:

json
"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에서 내보내십시오.

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 및 출력 레이아웃도 참조하십시오.

MIT 라이선스에 따라 배포됩니다.