JSON

UI 복사본을 소스에서 t("…") 대신 로케일별 중첩 JSON 파일(예: src/i18n/en/translation.json)에 보관하는 프로젝트용으로 설계되었습니다. CLI는 해당 파일의 문자열 값을 탐색하고, 활성 LLM 공급자를 통해 번역하며, json[].outputPathTemplate를 사용하여 로케일별 출력을 작성합니다. translate-docs 및 translate-svg(cacheDir)와 동일한 SQLite 캐시를 사용합니다.

이 파이프라인은 작동하지 않습니다 extract — strings.json 카탈로그가 없습니다. features.translateJson로 활성화하고 최상위 json[]에 하나 이상의 항목을 추가하세요.

로케일별 모델 재정의

translate-json는 대상 로캘마다 모델을 해결합니다: localeModels(locale)가 먼저 구성되면 translationModels를 사용합니다. 중첩된 JSON 번들을 위한 전용 모델이 특정 로캘에서 이점을 제공하는 경우에 이 방법을 사용하십시오. 예를 들어 zh-Hans / zh-Hant 테마 파일을 참조하십시오. 공급자 및 모델 참조.

1단계: 중첩된 JSON 초기화

ai-i18n-tools init -t ui-json-bundles [-P <provider>]

이 템플릿은 features.translateJson: true을(를) 설정하고, UI 추출 및 문서 번역을 비활성화하며, src/i18n/en/translation.json를 가리키고 출력이 src/i18n/{llocale}/translation.json인 단일 json[] 블록을 스캐폴드합니다. 또한 기본 provider / providers 블록(-P <provider>을(를) 전달하지 않으면 openrouter)을 포함합니다 — translate-json 또는 sync을(를) 실행하기 전에 일치하는 API 키를 설정하거나 로컬 Ollama를 사용하세요; 제공자 및 API 키를 참조하세요. 리포지토리 레이아웃에 맞게 sourceLocale, targetLocales, contentPaths, outputPathTemplate을(를) 편집하세요.

2단계: json[] 구성

각 json[] 블록은 하나의 파이프라인을 설명합니다:

• contentPaths — 하나 이상의 .json 파일, 디렉터리 또는 glob (예: "src/i18n/en/translation.json" 또는 "src/i18n/en/overrides/*.json"). 경로는 프로젝트 루트에서 해석됩니다.
• outputPathTemplate — 필수 항목. 각 대상 로케일 파일을 어디에 작성할지 지정합니다. 사용 가능한 자리표시자: {locale}, {LOCALE}, {llocale} (소문자 로케일, Astro 라우트 폴더에 유용), {stem}, {basename}, {extension}, {relativeToSourceRoot}.
• targetLocales (선택 사항) — 이 블록에만 적용되는 하위 집합. 그렇지 않으면 최상위 targetLocales이 적용됩니다.
• keyPolicy — 번역 가능한 문장과 안정적인 식별자 중 어떤 JSON 키가 포함되어 있는지 지정합니다 (아래 참조).
• description (선택 사항) — CLI 헤더 및 status 출력에 표시됩니다.

예시 (여러 소스 파일, 소문자 로케일 폴더):

{
  "sourceLocale": "en",
  "targetLocales": ["de", "fr", "pt-BR"],
  "features": {
    "translateJson": true
  },
  "cacheDir": ".translation-cache",
  "json": [
    {
      "description": "App UI bundle",
      "contentPaths": [
        "src/i18n/en/translation.json",
        "src/i18n/en/overrides/*.json"
      ],
      "outputPathTemplate": "src/i18n/{llocale}/{basename}",
      "keyPolicy": {
        "mode": "denylist",
        "skipKeys": ["id", "slug", "href", "url", "key", "code"],
        "translateKeys": []
      }
    }
  ]
}

keyPolicy

mode	동작
allowlist	translateKeys와 일치하는 키만 번역합니다 (도트 경로; minimatch glob).
denylist	skipKeys와 일치하는 키를 제외한 모든 문자열 값을 번역합니다.
both	먼저 translateKeys을 적용한 후 skipKeys와 일치하는 항목을 제거합니다.

경로는 도트 표기법을 사용합니다 (nav.home.label). slug과 같은 단순 이름은 깊이에 관계없이 마지막 키 세그먼트와 일치합니다.

3단계: JSON 번들 번역

ai-i18n-tools translate-json

선택적 플래그 (translate-docs과 동일한 개념): -l / --locale는 대상 하위 집합에 사용, -p / --path는 파일 제한에 사용, --dry-run, --force (일치하는 파일의 파일 추적 및 세그먼트 캐시 지우기), --force-update (파일 해시가 일치할 때 다시 처리; 세그먼트 캐시는 여전히 적용됨), -b / --batch-concurrency, --prompt-format (xml | json-array | json-object).

JSON 전용 프로젝트는 다음을 실행할 수 있습니다:

ai-i18n-tools sync --no-ui --no-svg --no-docs

UI 또는 문서도 활성화된 경우, sync은(는) translate-docs 이후 translate-json을 실행합니다 (--no-json이(가) 설정되지 않은 경우). --no-json를 사용하여 JSON을 건너뛸 수 있습니다.

파일 및 로케일별 커버리지를 확인하세요:

ai-i18n-tools status

translateJson이 켜져 있을 때, status은 json[] 섹션을 출력합니다 (✓ 최신 상태, ● 오래되거나 누락됨).

JSON과 다른 파이프라인

상황	사용
JS/TS/Astro의 t("…") / i18n.t("…")에 있는 UI 문자열	UI 문자열 — extract + translate-ui
Docusaurus write-translations 카탈로그 ({ "key": { "message": "…", "description": "…" } })	문서 — docs[].docusaurusCatalogDir + translate-docs, 아님 json[]
VitePress 테마/네비게이션/사이드바 문자열	문서 — docsOutput.vitepressThemeCatalog + translate-docs; json[]를 사용하지 마세요 — VitePress 통합 참조
Nextra _meta.ts 라벨 및 테마 사전 .ts	문서 — translate-docs (style: "nextra"일 때 자동 _meta, 선택적 nextraDictionaryPath); json[]를 사용하지 마세요 — Nextra 통합 참조
Fumadocs meta.json 라벨 및 UI 오버라이드 카탈로그	문서 — translate-docs (style: "fumadocs"일 때 자동 meta.json, 선택적 fumadocsUiCatalog); json[]를 사용하지 마세요 — Fumadocs 통합 참조
독립형 중첩 로케일 JSON (ZenBrowser 스타일 translation.json 트리)	JSON — json[] + translate-json
<text> / <title> / <desc>가 포함된 그림 .svg 파일	features.translateSVG + svg + translate-svg (선택 사항, 세 가지 주요 파이프라인 중 하나가 아님)

필드 참조: 구성 참조의 json. 정리를 위한 캐시 키는 file_tracking에서 json-block:{blockIndex}:{projectRelPath}을 사용합니다.