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 <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 사이드바 레이블, 테마 사전 모듈을 한 번의 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[] 블록을 구성하세요:

{
  "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 테마 사전 문자열에 절대 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()

기본값: translate-docs 내에서 _meta.ts / _meta.tsx 객체 리터럴 문자열이 번역됩니다. 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](/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).*)',
  ],
}

사이트 로케일 코드 vs 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 및 출력 레이아웃도 참조하십시오.