Skip to content

아키텍처 ​

아키텍처 개요 ​

코드베이스는 4개의 계층으로 구성됩니다. 이 섹션을 개념 모델에 사용하고, 파일 수준의 세부 정보가 필요할 때 소스 트리를 여세요.

sync 실행이 함께 작동하는 방식 ​

sync(및 개별 번역 명령)은 활성화된 기능을 순서대로 실행합니다.

단계명령기능
1extract → translate-uiUI 소스 스캔 → strings.json 업데이트 → 플랫 로케일 JSON 채우기(de.json, …)
2translate-svg (선택 사항)config.svg 아래의 SVG 텍스트 번역
3translate-docs마크다운, MDX, .astro 페이지 번역; Docusaurus 카탈로그 JSON; Nextra _meta / 사전 .ts; VitePress 테마 카탈로그
4translate-json (선택 사항)json[] 아래의 중첩된 JSON 리프 번역

모든 파이프라인은 동일한 핵심 루프를 따릅니다. 세그먼트 추출 → 구문 보호 → 일괄 처리 → 캐시 조회 또는 LLM 호출 → 출력 쓰기. 중간의 공유 서비스(구성, 자리 표시자, 캐시, 용어집, LlmClient)는 공유 인프라에 설명되어 있습니다.

모듈 맵 ​

계층폴더역할
진입src/cli/CLI 명령: init, extract, mark-html, translate-ui, translate-docs, translate-json, translate-svg, sync, status, dashboard, …
파이프라인src/extractors/JS/TS, HTML 마커, 마크다운, JSON, SVG, .astro에서 세그먼트 추출
src/processors/자리 표시자 보호, 일괄 처리, 유효성 검사, 링크 다시 쓰기
공유src/core/구성, 유형, SQLite 캐시, 프롬프트, 출력 경로, 로케일 유틸리티
src/api/LlmClient — 모델 대체 기능이 있는 공급자 독립적인 채팅 클라이언트(Vercel AI SDK)
src/glossary/프롬프트용 용어집 로딩, 용어 힌트 및 선택적 프로젝트 컨텍스트 파일
src/utils/로거, 해싱, 무시 파서, 표시 너비 테이블, .env 로더
앱 런타임src/runtime/i18next 도우미 및 표시 유틸리티 — 'ai-i18n-tools/runtime'로 내보내짐(런타임 도우미)
도구 UI (도그푸딩)src/i18n/, src/dashboard-app/, src/server/이 패키지 자체의 CLI 및 번역 대시보드를 현지화합니다. — 프로젝트 콘텐츠와는 별개로 (자체 현지화)

프로그래밍 방식으로 사용하기 위한 모든 것은 src/index.ts에서 다시 내보내집니다(프로그래밍 API).

파이프라인 요약 ​

파이프라인섹션입력 → 출력
UI 문자열UI 문자열 내부소스 파일 → strings.json → 플랫 {locale}.json
문서문서 내부Markdown / MDX / .astro / Docusaurus JSON → docs[].outputDir 아래의 로케일별 파일
JSON 번들JSON 내부json[] 아래의 중첩 JSON → 로케일별 JSON 파일
SVG문서 내부 — 추출기config.svg 아래의 SVG 파일 → 번역된 SVG 사본

UI 문자열 내부 ​

단계구성 요소결과
1소스 파일 (JS/TS; 선택 사항 .astro / .html)디스크의 파일
2UIStringExtractor (Babel, ui-string-babel.ts 경유)MD5 해시로 키 지정된 세그먼트
3strings.json마스터 카탈로그: { hash: { source, translated, models?, locations? } }
4LlmClient.translateUIBatch()소스 문자열의 JSON 배열 → 번역 (+ 배치당 모델 ID)
5de.json, pt-BR.json, …플랫 맵: 소스 문자열 → 번역 (모델 메타데이터 없음)

UIStringExtractor ​

ui-string-babel.ts 내의 extractUiCallsFromFileContent은(는) t("literal") 및 i18n.t("literal") 호출을 찾습니다. JS 및 TS 파일은 @babel/parser(모듈 소스, TypeScript 및 JSX)로 구문 분석됩니다. .astro 소스( ui.uiExtractor.extensions에 나열된 경우)의 경우, 동일한 함수가 프런트매터 및 템플릿 {expression} 블록을 구문 분석하고 동일한 funcNames 규칙을 적용합니다. 함수 이름과 파일 확장자는 ui.uiExtractor를 통해 구성할 수 있습니다(ui.reactExtractor은(는) 지원되는 별칭입니다). extract은(는) 또한 추가 입력을 동일한 카탈로그로 병합합니다: includePackageDescription가 활성화된 경우(기본값) 프로젝트 package.json description과, includeUiLanguageEnglishNames이(가) true인 경우 번들로 제공되는 UI 언어 마스터 카탈로그(sourceLocale + targetLocales에서 빌드됨)의 각 englishName를 병합합니다(소스에서 이미 발견된 문자열이 우선권을 유지합니다; languagesManifestPath을(를) 읽지 않습니다). extract은(는) 또한 languagesManifestPath에서 ui-languages.json을(를) 재생성합니다. 세그먼트 해시는 잘라낸 소스 문자열의 MD5 처음 8개 16진수 문자입니다. 이는 strings.json의 키가 됩니다.

.html / .htm 소스( ui.uiExtractor.extensions에 나열된 경우)의 경우, extract는 대신 파일을 html-i18n-marks.ts를 통해 라우팅하며, 이는 data-i18n / data-i18n-title / data-i18n-placeholder / data-i18n-alt / data-i18n-aria-label 마커 속성( ui.uiExtractor.htmlI18nAttributes을 통해 구성 가능)을 스캔합니다. 베어 마커는 요소 자체의 textContent 또는 속성에서 소스 텍스트를 가져오며, 값 있는 마커( data-i18n="Key")는 값을 사용합니다. data-i18n-locale-src 및 data-i18n-locale-href는 브라우저 런타임을 위해 예약되어 있으며 절대 추출되지 않습니다. 동일한 모듈이 mark-html 명령을 구동하며, 이 명령은 베어 마커( alt 및 aria-label 포함)를 자동으로 삽입하고 로케일 URL 마커는 절대 삽입하지 않습니다. HTML 파일은 바벨 패스에 도달하지 않습니다. 문서 outputDir 아래에 생성된 로케일 HTML은 이 스캔에서 제외됩니다.

순수 Astro SSG 사이트는 i18next를 건너뛸 수 있습니다. 빌드 시 플랫 {locale}.json을 로드하고 소스 텍스트 키로 t('source text')을 확인합니다. 소스 언어는 sourceLocale이며 모든 언어가 될 수 있습니다(examples/astro-website/src/i18n/t.ts 및 UI 문자열 — Astro 웹사이트 참조).

일반 HTML 앱은 t() 호출 대신 마커 속성을 사용하여 동일한 카탈로그 모델을 따릅니다. — HTML 번역을 위한 마킹을 참조하세요. 바로 사용할 수 있는 스크립트는 ai-i18n-tools/html-runtime/i18n.js입니다.

로케일당 하나의 파일이 되어야 하는 정적 HTML은 이 카탈로그가 아닌 문서 파이프라인(translate-docs 내부의 HtmlTemplateExtractor)입니다. HTML 페이지를 참조하세요.

strings.json ​

마스터 카탈로그의 구조는 다음과 같습니다:

json
{
  "a1b2c3d4": {
    "source": "The English string",
    "translated": {
      "de": "Der deutsche Text",
      "pt-BR": "O texto em português"
    },
    "models": {
      "de": "anthropic/claude-3.5-haiku",
      "pt-BR": "openai/gpt-4o"
    },
    "locations": [{ "file": "src/app/page.tsx", "line": 51 }]
  }
}

models (선택 사항) — 로케일별로, 해당 로케일의 마지막 성공적인 translate-ui 실행 후 해당 번역을 생성한 모델입니다(또는 텍스트가 번역 대시보드에서 저장된 경우 user-edited). locations (선택 사항) — extract가 문자열을 찾은 위치입니다(스캐너 + 패키지 설명 줄; 번들된 마스터 englishName 문자열은 locations를 생략할 수 있음).

extract는 새 키를 추가하고 스캔에 여전히 존재하는 키(스캐너 리터럴, 선택적 설명, 선택적 번들된 마스터 englishName)에 대한 기존 translated / models 데이터를 보존합니다. translate-ui는 누락된 translated 항목을 채우고, 번역하는 로케일의 models를 업데이트하며, 플랫 로케일 파일을 작성합니다.

ui-languages.json 매니페스트 — { code, label, englishName, direction }의 JSON 배열(BCP-47 code, UI label, 참조 englishName, "ltr" 또는 "rtl"). generate-ui-languages 또는 extract를 사용하여 sourceLocale + targetLocales 및 번들된 마스터 data/ui-languages-complete.json에서 프로젝트 파일을 빌드합니다.

단일화된 로케일 파일 ​

각 대상 로케일은 원본 문자열 → 번역을 매핑하는 평면화된 JSON 파일(de.json)을 가집니다 (models 필드 없음):

json
{
  "The English string": "Der deutsche Text",
  "Save": "Speichern"
}

i18next는 이를 리소스 번들로 로드하고 원본 문자열을 키로 하여 번역을 조회합니다 (키를 기본값으로 사용하는 모델).

UI 번역 프롬프트 ​

buildUIPromptMessages은 다음을 수행하는 시스템 및 사용자 메시지를 구성합니다:

  • 소스 및 대상 언어를 식별합니다(localeDisplayNames 또는 ui-languages.json의 표시 이름 기준).
  • 대상 로캘에 예상 문자 체계가 있는 경우(명시적 BCP-47 스크립트 또는 hi → 데바나가리, ar → 아랍 문자, ja → 일본어 가나/한자와 같은 언어 기본값) 스크립트 지시어를 앞에 추가합니다.
  • 문자열의 JSON 배열을 전송하고 그에 대한 번역의 JSON 배열을 반환하도록 요청합니다.
  • 사용 가능한 경우 용어집 힌트를 포함합니다.

LlmClient.translateUIBatch는 각 모델을 순서대로 시도하며, 구문 분석, 네트워크 또는 잘못된 스크립트 오류 발생 시 대체합니다(원어 스크립트 로케일에 대한 로마자/라틴어 대체 포함). CLI는 대상 로케일별로 localeModels, 선택적 uiModels, 그리고 translationModels에서 해당 목록을 빌드합니다(AI 모델 참조).


문서 내부 ​

단계구성 요소결과
1Markdown / MDX / JSON / .astro 파일 (translate-docs)소스 파일
2MarkdownExtractor / JsonExtractor / AstroTemplateExtractorsegments[] — 해시 + 콘텐츠가 있는 유형화된 세그먼트
3PlaceholderHandler보호된 텍스트 — HTML, 주의 사항, 앵커, MDX, URL, 인라인 코드, 토큰으로 마스킹된 강조
4splitTranslatableIntoBatchesbatches[] — 개수 + 문자 제한별로 그룹화됨
5TranslationCache 조회캐시 적중 → 건너뛰기; 누락 → LlmClient.translateDocumentBatch
6PlaceholderHandler.restoreAfterTranslation최종 텍스트 — 자리 표시자 복원됨
7resolveDocumentationOutputPath출력 파일 — Docusaurus 레이아웃 또는 플랫 레이아웃

추출기 ​

모든 추출기는 BaseExtractor를 확장하고 extract(content, filepath): Segment[]를 구현합니다.

  • MarkdownExtractor - 마크다운을 유형별 세그먼트(frontmatter, heading, paragraph, code, admonition)로 분할합니다. YAML 프런트매터는 번역 불가능으로 분류됩니다(slug, id 및 기타 라우팅 키는 안정적으로 유지됨). 최상위 수준 export ... 블록(예: React 컴포넌트 정의)은 기존 import ... 처리와 함께 번역 불가능한 other 세그먼트로 분류됩니다. 대문자 JSX 태그로 시작하는 여러 줄 블록(예: <Tabs> 블록)은 번역 가능한 단락으로 분류됩니다. 번역 불가능한 세그먼트(코드 블록, 원시 HTML)는 그대로 보존됩니다.
  • AstroTemplateExtractor - .astro 마케팅 페이지에 대한 구문 분석 및 바꾸기(doc-translate.ts에서 translateAstroFile를 통해 translate-docs). 사용자에게 표시되는 HTML 텍스트 노드와 번역 가능한 속성(alt, title, aria-label, placeholder)을 추출하고, 사용자에게 표시되는 경우 템플릿 {expression} 블록 내의 문자열 리터럴도 추출합니다. 프런트매터 TypeScript, <script>, <style>, 보호된 속성/키 값 및 t('…') 내의 리터럴은 건너뜁니다. 재조립 시 출력 경로가 더 깊어지면(예: src/pages/de/index.astro) 상대적 가져오기를 조정합니다. Astro 웹사이트 페이지를 참조하세요.
  • JsonExtractor - Docusaurus JSON 레이블 파일에서 문자열 값을 추출합니다(MDX 본문이 아닌 Docusaurus UI 카탈로그).
  • SvgExtractor - SVG에서 <text>, <title>, <desc> 콘텐츠를 추출합니다(translate-docs가 아닌 translate-svg이 config.svg 아래의 파일에 사용).
  • html-i18n-marks.ts - extract에서 .html / .htm 소스용으로, 그리고 mark-html 명령에서 사용하는 집중형 HTML 태그 스캐너입니다. collectHtmlI18nStrings / collectHtmlI18nLocations는 data-i18n* 마커 속성을 읽습니다(일반 마커 → 요소 textContent / title / placeholder; 값이 있는 마커 → 값). markHtmlContent은 일반 마커를 리프 텍스트 / 제목 / 플레이스홀더 요소에 삽입합니다(멱등성, data-i18n-ignore 존중, 코드와 유사하거나 혼합 콘텐츠인 요소는 건너뜁니다). 공유되는 normalizeI18nText 도우미는 빌드 시간 키를 브라우저 런타임과 동일하게 유지합니다.

Astro 하이브리드 사이트(UI + 페이지 HTML) ​

일반 Astro 앱은 종종 UI 문자열과 문서를 하나의 구성에서 모두 활성화합니다 (참조: examples/astro-website/):

계층메커니즘출력
템플릿 HTMLAstroTemplateExtractor + translate-docsdocs[].outputDir 아래의 로케일별 .astro
프런트매터 / t('…')ui-string-babel.ts + extract + translate-ui플랫 public/locales/{locale}.json (소스 언어 문자열을 키로 사용, sourceLocale는 모든 언어 가능)

sync 명령은 활성화된 단계를 순서대로 실행합니다: 추출 다음 UI 번역 (features.translateUIStrings인 경우) → 선택적 SVG 번역 → 문서 번역 → 선택적 JSON 번역 (--no-ui, --no-svg, --no-docs 또는 --no-json로 건너뛰지 않는 한). 초기 템플릿 ui-astro-website는 UI 문자열만 스캐폴드합니다. 페이지 HTML을 위해 docs[] 및 features.translateDocs를 추가합니다.

제목 앵커 삽입 (write-heading-ids CLI) ​

write-heading-ids 명령은 문서 마크다운을 위한 로컬, 비-LLM 전처리기입니다. 구현 방식: src/cli/write-heading-ids.ts이 파일 탐색을 조정하고, src/markdown/write-heading-ids-core.ts가 줄을 구문 분석하여 앵커를 삽입합니다.

유효한 구성에는 최소 하나의 docs[] 블록이 필요합니다. 각 블록에 대해 contentPaths 아래의 .md / .mdx 파일을 수집하고, 프로젝트의 .translate-ignore 규칙(문서 번역과 동일한 개념)을 적용하며, 선택적으로 --path / --file로 하위 트리로 제한합니다. 각 파일은 applyHeadingAnchorsToMarkdown로 변환됩니다: 펜스된 코드 블록 외부의 모든 평면 ATX 제목(# …부터 ###### …까지)에 대해, 모든 형식의 기존 제목 ID가 선택된 스타일로 대체됩니다. HTML 스타일은 접미사가 없는 제목 위의 줄에 <a id="slug"></a>을 작성합니다; --slug-style mdx-comment은 제목 줄에 {/* #slug */}를 작성합니다(그리고 선행 HTML 앵커를 삭제합니다). 슬러그는 항상 현재 제목 텍스트에서 가져옵니다. --remove은 HTML 앵커, 클래식 {#id} 접미사 및 MDX 주석 ID를 제거하지만 새로 작성하지는 않습니다. 슬러그 알고리즘은 일반적인 생태계와 일치합니다 — github(기본값), bitbucket, gitlab, pymdown(선택적 유니코드 정규화 / 퍼센트 인코딩 플래그), azure-devops, 추가로 mdx-comment(깃허브 슬러그 + MDX 주석 출력) — 따라서 앵커 ID가 기존 도구(doctoc, PyMdown, Docusaurus 등)와 일관성을 유지합니다. --dry-run은 작성하지 않고 예정된 편집을 보고합니다.

소스 패스 이후, 동일한 명령이 각 로케일의 기존 번역된 마크다운(resolveTranslatedOutputPath)에 해당 영어 id들을 다시 배치합니다. 번역된 제목은 재슬러깅되지 않으며, 제목 중간의 {#id} / {/* #id */}는 선택된 스타일이 기대하는 접미사(또는 HTML 앵커)로 다시 이동됩니다. 누락된 로케일 파일은 건너뜁니다.

이 명령은 translate-docs 또는 sync 내부에서 실행되지 않습니다. 번역 또는 게시 전에 소스 파일 내 조각 ID를 안정적으로 유지하고자 할 때 명시적으로 실행해야 합니다.

자리 표시자 보호 ​

번역 전에 민감한 구문은 LLM 손상을 방지하기 위해 불투명한 토큰으로 교체되며, 이 순서로 적용됩니다 (복원은 반대 순서입니다):

  1. 펜스 코드 블록(백틱 또는 물결표 3개 이상, 더 짧은 펜스를 감싸는 더 긴 펜스 포함) - 정보 문자열을 포함한 전체 펜스는 {{CDF_N}}로 대체되며 다른 구조 토큰과 순서대로 유지됩니다. 이는 ::: code-group 또는 ::: tip와 같은 컨테이너 내부의 샘플을 제자리에 유지합니다. 펜스 정보 문자열(VitePress 탭 레이블)은 원본 언어로 유지됩니다. 닫히지 않은 시작 태그는 텍스트로 남겨져 나중에 오는 컨테이너 닫는 태그가 삼켜지지 않도록 합니다.
  2. 헤딩 ID 접미사(ATX 헤딩 끝에 있는 기존 {#id} / MDX {/* #id */}) — 줄에서 완전히 제거되며 모델로 전송되지 않습니다. 복원 후에는 일치하는 헤딩 끝에 다시 고정되어 Docusaurus가 유효한 ID를 계속 인식하도록 합니다. 헤딩 중간 주석은 텍스트에 남아 있으며 나중에 MDX / {#…} 레이어에서 처리됩니다. 마스킹된 펜스 내부의 헤딩은 제거되지 않습니다.
  3. HTML 태그 및 주석 (<strong>, <!-- ... --> 등) - 알려진 허용 목록의 소문자 HTML 태그는 {{HTM_N}} 토큰으로 대체됩니다. 대문자 JSX 태그 (<Highlight>, <Tabs>, </Tab>)는 MDX 레이어(6단계)에서 별도로 처리됩니다.
  4. 어드모니션 마커 (:::note, :::) - 시작 줄의 지시어 접두사만 {{ADM_OPEN_N}}로 대체됩니다. 같은 줄의 제목은 모델이 번역하도록 남겨둡니다. 정확한 원본 텍스트로 복원됩니다.
  5. 문서 앵커 (HTML <a id="…">, 헤딩 중간에 남은 Docusaurus {#…}) - 원문 그대로 보존.
  6. 엠디엑스 전용 구성 (src/processors/mdx-placeholders.ts):
    • 엠디엑스 주석 ({/* … */}, 행 끝 접미사가 아니었던 중간 헤딩의 {/* #my-id */} 포함) {{MDX_N}}로 대체됩니다.
    • 대문자로 시작하는 제이에스엑스 태그 (<Highlight>, <Tabs>, <TabItem>, <TOCInline />, </Highlight>) - {{MDX_N}}로 보존되며, 번역 가능한 문자열 속성(label, tooltip, aria-label)은 속성 이름이 docs[].protectAttributes에 나타나지 않는 한 태그 내부에서 {{JXA_N}}로 다시 작성됩니다; label:은 <Tabs values={[ { label: '…' } ]}> 객체 리터럴 내부( docs[].protectKeys로 건너뛸 수 있음 )와 <TabItem value="…">( label 속성이 없을 때, 소문자 슬러그 유사 값은 건너뜀 )에서도 추출됩니다. 세그먼트에 ||JXA_N: …|| 행으로 추가되고 restoreMdx으로 다시 병합됩니다.
    • 엠디엑스 중괄호 표현 ({frontMatter.title}, style={{…}}) - 깊이 인식 매칭으로 {{MDX_N}}로 대체됩니다.
  7. 마크다운 유알엘 (](url), src="…") - 번역 후 맵에서 복원됩니다.
  8. 인라인 코드 범위 (`code`) 및 굵게 감싼 인라인 코드 (**코드**) - 보존됩니다.
  9. 마크다운 강조(선택 사항, CJK/RTL 로케일에 대해 자동 활성화) - 강조 구분 기호가 마스킹됩니다.

모델이 반환된 후 translate-docs는 맵을 복원하고 세그먼트를 검증합니다. 검증 시에는 동일한 중괄호 두 개 토큰의 다중 집합이 있어야 하고, 구조적 토큰({{HTM_N}}, 경고 마커, {{CDF_N}})은 순서가 지정된 하위 시퀀스를 유지해야 합니다(단, {{ILC_N}} / {{URL_N}} / {{SE}}와 같은 콘텐츠 토큰은 어순에 따라 이동할 수 있음). 또한 복원된 HTML 태그 종류는 보호되지 않은 소스와 일치해야 하며, 남아 있는 모든 중괄호 두 개 식별자는 소스에 이미 존재했던 것이어야 합니다(따라서 새로 만들어진 토큰은 실패합니다). 문서 프롬프트는 모델에 각 토큰을 한 번씩 복사하고 구조적 토큰 순서를 유지하며 새로운 중괄호 두 개 래퍼를 만들지 않도록 요청하지만, 기계적 검사가 최종 결정권을 가집니다.

Astro 템플릿 및 MDX JSX에 대한 공유 속성/키 보호는 src/processors/expression-attribute-protection.ts에 구현되어 있으며 docs[].protectAttributes 및 docs[].protectKeys에 의해 블록별로 구동됩니다(protectAttributes / protectKeys 참조).

캐시(TranslationCache) ​

SQLite 데이터베이스(node:sqlite를 통해)는 정규화된 콘텐츠의 SHA-256 해시 값 중 앞 16자리 16진수 문자를 사용하여 (source_hash, locale)를 키로 하고 translated_text, model, filepath, last_hit_at 및 관련 필드를 포함하는 행을 저장합니다. 공백은 압축됩니다.

각 실행 시, 세그먼트는 해시 × 로케일로 조회됩니다. 캐시 미스만 LLM으로 전달됩니다. 번역 후, 현재 번역 범위 내에서 적중되지 않은 세그먼트 행에 대해 last_hit_at가 재설정됩니다. 문서 번역 중 성공적인 캐시 적중은 해당 세그먼트에 대한 오래된 translation_failures 행을 지웁니다.

cleanup는 먼저 sync --force-update을(를) 실행한 다음 다음을 수행합니다.

  • 오래된 세그먼트 행을 제거합니다(null last_hit_at / 빈 파일 경로).
  • 해결된 소스 경로가 디스크에 없을 때 file_tracking 키를 정리합니다(doc-block:…, json-block:…, svg-files:… 등).
  • 메타데이터 파일 경로가 없는 파일을 가리키는 번역 행을 제거합니다.
  • 고아 translation_failures 행을 정리합니다.
  • 해결된 소스 경로가 디스크에 없는 고아 markdown_source_issues 행을 정리합니다.
  • 구성에 없는 로케일에 대한 캐시 행을 삭제합니다(sourceLocale, 루트 targetLocales, 그리고 블록별 docs[] / json[] targetLocales; SQLite 전용 — 생성된 파일을 삭제하려면 purge-locale을(를) 사용하세요).

cache.db은(는) --backup <path>이(가) 전달되어야만 백업되며, 이때 먼저 해당 경로에 백업이 작성됩니다.

청구된 모델 호출(수락된 번역 및 폐기된 재시도)은 api_calls에 저장됩니다. 호출을 기록하는 명령을 실행한 후, UTC 기준 7일이 지난 세부 정보 행은 월별 api_totals로 집계됩니다. usage 및 대시보드의 사용량 및 비용 보기는 두 테이블을 결합합니다. 사용량 및 비용을 참조하세요.

용어집 Context 노트 및 glossary.contextFiles은 지문 처리되어 (prompt_context_hash) UI, 문서, JSON, SVG 및 교정 프롬프트에 주입됩니다. 해당 지침을 변경하면 다음 실행 시 일치하는 캐시된 세그먼트 및 파일 추적 행이 무효화됩니다. 대시보드 user-edited 캐시 행은 유지됩니다. 강제되지 않은 행에서 선호하는 용어집 번역만 변경하면 --force / --force-update까지 기존 캐시가 그대로 유지됩니다. Force 행은 저장된 텍스트에 강제 번역이 이미 포함되어 있지 않은 경우, 해당 용어가 포함된 소스 세그먼트에 대해서만 캐시를 놓치며, 출력에 여전히 해당 내용이 누락된 파일의 경우 변경되지 않은 파일 건너뛰기가 거부됩니다. 해당 행에서 Context을(를) 비워 두십시오. 컨텍스트 노트는 여전히 전체 로케일을 새로 고칩니다. 마크다운은 또한 인용된 2~5단어 UI 레이블(카탈로그 키 또는 시드된 레이블 형태의 접두사)을 누락하는 번역된 세그먼트를 거부합니다. 인용은 굵게 표시되거나, 인라인 코드이거나, 제목이거나, 해당 레이블만 있는 줄입니다. 문장 내의 제목 대소문자는 힌트이므로 번역은 굴절될 수 있습니다 (힌디어 Cursor account은(는) 사전 형태인 कर्सर खाता 대신 कर्सर खाते이(가) 될 수 있습니다). Sign in과(와) 같은 단일 내용 단어 레이블은 힌트로 유지됩니다. 검사는 번역의 대소문자를 무시하므로, 소스가 인용할 때 문장의 소문자 레이블도 여전히 유효합니다. 동일한 단어를 사용하는 일반 산문은 그것들을 굴절시킬 수 있습니다. 시드된 접두사는 공유 번역이 플레이스홀더 없는 짧은 구문인 대문자로 시작하는 레이블이어야 합니다. 문장 어간은 시드되지 않습니다. 해당 검사는 다음 모델을 다시 시도하며 세그먼트를 분할하지 않습니다.

translate-docs 명령은 파일 추적도 사용하여 기존의 최신 출력이 있는 변경되지 않은 소스에 대해 작업을 완전히 건너뛸 수 있습니다. --check-cache는 예상되는 쓰기 시스템으로 로케일을 다시 열어 캐시된 세그먼트가 다시 유효성 검사되도록 합니다. --force-update는 세그먼트 캐시를 계속 사용하면서 모든 로케일에 대해 파일 처리를 다시 실행합니다. --force는 파일 추적을 지우고 API 번역을 위한 세그먼트 캐시 읽기를 우회합니다. 마크다운 세그먼트에 대해 시도된 모델이 AST 유효성 검사에 실패하면 translate-docs는 세그먼트를 점진적으로 분할하고 더 작은 부분으로 다시 시도할 수 있습니다 (docs[].segmentSplitting.qualityRetrySplit, 기본적으로 켜짐). 동일한 품질 오류가 세 번 발생하면 해당 모델 목록이 조기에 종료됩니다. 전체 플래그 테이블은 문서 — 캐시 동작 및 플래그를 참조하십시오.

배치 프롬프트 형식: translate-docs --prompt-format은 LlmClient.translateDocumentBatch에 대해서만 XML(<seg> / <t>) 또는 JSON 배열/객체 모양을 선택합니다. 추출, 자리 표시자 및 유효성 검사는 변경되지 않습니다. 배치 프롬프트 형식을 참조하십시오.

출력 경로 해석 ​

resolveDocumentationOutputPath(config, cwd, locale, relPath, kind)은 소스 기준 경로를 출력 경로에 매핑합니다:

  • nested 스타일(기본값): 마크다운의 경우 {outputDir}/{locale}/{relPath}.
  • doc-system 스타일: docsRoot 아래에서 출력은 {outputDir}/{locale}/[localeSubpath/]{relativeToDocsRoot}를 사용합니다. docsRoot 외부 경로는 중첩된 레이아웃으로 대체됩니다. 별칭: docusaurus(기본 localeSubpath = Docusaurus 플러그인 경로), astro-starlight(기본 빈 localeSubpath), vitepress(doc-system와 동일하며 빈 localeSubpath 포함; BCP-47 폴더 대소문자 유지).
  • flat 스타일: {outputDir}/{stem}.{locale}{extension}. flatPreserveRelativeDir가 true인 경우, 소스 하위 디렉터리는 outputDir 아래에 유지됩니다.
  • 사용자 지정 pathTemplate: {outputDir}, {locale}, {LOCALE}, {relPath}, {stem}, {basename}, {extension}, {docsRoot}, {relativeToDocsRoot}을 사용하는 모든 마크다운 레이아웃.
  • 사용자 정의 jsonPathTemplate: JSON 레이블 파일을 위한 별도의 사용자 정의 레이아웃으로, 동일한 플레이스홀더 사용.
  • linkRewriteDocsRoot은 번역된 출력이 기본 프로젝트 루트가 아닌 다른 위치에 루트를 둘 때, 평면화된 링크 재작성기가 올바른 접두사를 계산하도록 도와줍니다.

단일 링크 재작성 ​

docsOutput.style === "flat"인 경우, 번역된 마크다운 파일은 로케일 접미사와 함께 소스 옆에 배치됩니다. 페이지 간의 상대 링크는 readme.de.md의 [Guide](./guide.md)이(가) guide.de.md을(를) 가리키도록 다시 작성됩니다. rewriteRelativeLinks에 의해 제어됩니다(사용자 정의 pathTemplate 없이 플랫 스타일에 대해 자동 활성화됨). 동일한 패스는 postProcessing.regexAdjustments이(가) 실행되기 전에 마크다운이 아닌 에셋 URL에 파일별 깊이 접두사를 추가합니다 — 플랫 링크 재작성기를 참조하세요.


JSON 내부 ​

단계구성 요소결과
1json[].contentPaths파일 해결됨(파일, 디렉터리 또는 글로브)
2NestedJsonExtractorkeyPolicy에 의해 선택된 문자열 리프(점 경로 + 미니매치)
3PlaceholderHandler + 배치 + TranslationCache캐시 히트 → 건너뛰기; 미스 → LlmClient.translateDocumentBatch(공유 SQLite)
4NestedJsonExtractor.reassembleexpandJsonBlockOutputPath(outputPathTemplate)을 통한 출력 파일
  • NestedJsonExtractor (src/extractors/nested-json-extractor.ts)는 임의의 중첩된 JSON을 탐색하고 번역 가능한 문자열 리프당 하나의 세그먼트를 내보냅니다. keyPolicy.mode (allowlist, denylist 또는 both)는 점 표기법에 minimatch를 사용하여 경로를 필터링합니다 (slug와 같은 일반 이름은 최종 키 세그먼트와 일치합니다).
  • 캐시 파일 추적은 file_tracking에서 json-block:{blockIndex}:{projectRelPath}을 사용합니다 (문서 및 SVG와 동일한 cacheDir).
  • Docusaurus write-translations 카탈로그 ({ message, description } 모양)에는 사용되지 않습니다 — 이들은 문서 (translate-docs 내의 docs[].docusaurusCatalogDir + JsonExtractor)를 사용합니다.
  • t() UI 문자열에는 사용되지 않습니다 — UI 문자열 (strings.json + 플랫 번들).
  • CLI: translate-json; 오케스트레이션은 src/cli/translate-json-run.ts에서 수행됩니다. 초기화 템플릿: ui-json-bundles.

공유 인프라 ​

LlmClient ​

Vercel AI SDK( ai + @ai-sdk/openai-compatible )를 기반으로 구축된 공급자 독립적인 채팅 클라이언트입니다. 활성 공급자를 provider / providers에서 확인하고, 해당 공급자의 baseUrl + API 키에 대한 OpenAI 호환 클라이언트( createOpenAICompatible )를 빌드한 다음, 모든 호출을 generateText를 통해 라우팅합니다. OpenRouterClient는 더 이상 사용되지 않는 별칭으로 유지됩니다. 주요 동작:

  • 모델 대체: 확인된 목록의 각 모델을 순서대로 시도하며, 요청 또는 구문 분석 실패 시 대체합니다. 각 대상 로케일은 자체적으로 확인된 체인을 가집니다. 구성된 경우 localeModels(locale)가 먼저, 그 다음 uiModels (UI 파이프라인만), 그 다음 translationModels입니다. 문서, JSON 및 SVG 번역은 비-UI 체인을 사용하여 로케일별 클라이언트를 생성합니다. 대신 bench-models 명령은 구성된 ID당 하나의 단일 모델 클라이언트를 빌드합니다 (translationModels, uiModels 및 localeModels의 통합; translationModels: [id], 대체 없음). 이를 통해 각 모델의 시간과 가격을 독립적으로 측정할 수 있습니다.
  • 요청 시간 초과: 활성 공급자에서 requestTimeout (초) 또는 requestTimeoutMs이며, 그렇지 않으면 구성 상단의 동일한 키 (기본값 120초)를 사용하고 AbortSignal.timeout를 통해 각 요청을 중단합니다. CLI가 check-models (모든 공급자)에 대한 공급자의 모델 목록을 로드할 때 동일한 값이 GET /models에 적용됩니다. 알 수 없는 모델 ID를 삭제하는 선택적 사전 검사 필터는 활성 공급자가 OpenRouter일 때만 실행됩니다.
  • OpenRouter 추가 기능 (openrouter가 활성 상태일 때만): provider 요청 필드 및 HTTP-Referer / X-Title 헤더를 통한 처리량 라우팅. 모든 공급자에 대해 토큰 사용량이 보고됩니다. OpenRouter 및 Cheaper Inference는 청구된 USD 금액 (usage.cost; Cheaper Inference는 cheaper_inference.billing.billed_cost_usd로 대체)도 반환합니다. 공급자가 해당 금액을 생략하면 USD 비용은 providers.<name>.modelPricing에서 계산된 다음, 공급자 전체의 pricing 기본값, 그 다음 models.dev 입력 및 출력 정가에서 계산되어 api_calls 행에 저장됩니다. 공급자가 보고한 비용 (0 포함)은 절대 대체되지 않습니다. 알 수 없는 비용은 설정되지 않은 상태로 유지됩니다. 호출 가격 책정은 <cacheDir>/benchmark-scores.json의 models.dev 슬라이스만 읽습니다. languagebench 또는 Arena 파일을 다운로드하지 않습니다.
  • 디버그 트래픽 로그: debugTrafficFilePath가 설정된 경우, 요청 및 응답 JSON을 파일에 추가합니다 (프로그래밍 방식). CLI --debug-failed는 실패한 UI, 문서, JSON 및 SVG 번역 확인 시도에 대한 시스템/사용자 프롬프트, 원시 어시스턴트 응답 및 유효성 검사 오류와 함께 cacheDir 아래에 FAILED-TRANSLATION 파일을 작성합니다. 공급자 API / 빈 본문 실패는 프롬프트 전용 파일을 덤프하는 대신 콘솔에 출력됩니다.

suggest-models 및 대시보드 모델 탭은 LLM을 호출하지 않습니다. 이들은 languagebench ChrF 및 LMArena Arena Score에서 가져온 품질 지수로 활성 공급자의 채팅 카탈로그 순위를 매깁니다. 가격은 3:1 비율로 혼합된 100만 토큰당 USD 요금(카탈로그, 그 다음 models.dev, 그 다음 languagebench)입니다. --quality은 지수별로 정렬하고, --price는 품질-가격 파레토 프론티어를 탐색합니다. 이들은 선택적으로 providers.<name>.translationModels을(를) 대체합니다. 집계는 <cacheDir>/benchmark-scores.json에 있습니다. AI 모델 및 suggest-models를 참조하십시오.

설정 로드 ​

loadI18nConfigFromFile(configPath, cwd) 파이프라인:

  1. ai-i18n-tools.config.json(JSON)를 읽고 파싱합니다.
  2. mergeWithDefaults - defaultI18nConfigPartial와 깊은 병합을 수행하고, 모든 docs[].sourceFiles 항목을 contentPaths로 병합합니다.
  3. expandTargetLocalesFileReferenceInRawInput - targetLocales를 배열로 강제 변환하고 경로와 유사한 항목을 거부합니다(ui-languages.json 경로가 아닌 BCP-47 코드여야 함); mergeWithDefaults 동안 languagesManifestPath의 기본값은 {ui.flatOutputDir}/ui-languages.json입니다.
  4. expandDocumentationTargetLocalesInRawInput - 각 docs[].targetLocales 항목에 대해 동일하게 적용합니다.
  5. expandJsonTargetLocalesInRawInput - 각 json[].targetLocales 항목에 대해 동일합니다.
  6. parseI18nConfig - Zod 유효성 검사 + validateI18nBusinessRules.
  7. applyProviderOverrideToRawInput - -P / --provider가 CLI에 전달될 때.
  8. applyEnvOverrides - 설정된 경우 OPENROUTER_BASE_URL, OLLAMA_BASE_URL, I18N_SOURCE_LOCALE 및 I18N_TARGET_LOCALES를 적용합니다(API 키는 LlmClient 내에서 공급자별로 별도로 확인됩니다).
  9. augmentConfigWithUiLanguagesMaster - 번들로 제공되는 마스터 카탈로그에서 매니페스트 표시 이름을 첨부합니다.
  10. assertEffectiveLocalesInUiLanguagesMaster - 해당되는 경우 마스터 카탈로그에 대해 로케일 코드를 검증합니다.

init는 initConfigTemplates에서 다음 시작 구성을 작성합니다: ui-markdown(UI 문자열 및 플랫 README 블록), docs-markdown(README 및 Markdown만 해당), ui-docusaurus, ui-starlight, ui-vitepress(VitePress 문서 + vitepressThemeCatalog), ui-nextra(Nextra 문서 + nextraDictionaryPath), ui-astro-website(일반 Astro UI, .astro 페이지 번역을 위해 docs[] 추가), ui-json-bundles(JSON json[]만 해당), ui-python, ui-python-gettext, ui-python-django, ui-python-flask. --with-readme는 README.md이(가) 아직 목록에 없는 템플릿에 동일한 README 블록을 추가하고 translateDocs을(를) 켭니다. UI 문자열 — 초기화, README 및 Markdown 문서에 i18n 추가, Python 애플리케이션을(를) 참조하세요.

로거 ​

Logger는 ANSI 색상 출력과 함께 debug, info, warn, error 수준을 지원합니다. 자세한 모드(-v)는 debug을 활성화합니다. logFilePath이 설정된 경우 로그 라인은 해당 파일에도 기록됩니다.

자체 현지화 (도구 UI) ​

이 도구는 CLI 도움말, 트래픽이 많은 로그/요약/오류 메시지, 번역 대시보드 등 자체 UI를 사용자가 번역하는 콘텐츠와 별도로 현지화합니다.

  • 로케일 해결 (resolveUiLocale in src/core/ui-locale.ts): UI 로케일을 -L / --ui-lang > AI_I18N_LANG > 구성 uiLanguage > 호스트 OS 로케일(Intl.DateTimeFormat().resolvedOptions().locale)에서 선택합니다. 후보는 정규화되어 제공된 번들 세트와 정확히 일치하거나 가장 가까운 변형으로 매칭되며(예: pt-PT → pt-BR, en-US → en-GB), 소스 로케일(en-GB)로 폴백합니다. CLI는 도움말이 빌드되기 전(사전 파싱 argv 스캔)에 한 번 해결하고, 구성 로드 후 다시 해결하여 uiLanguage가 적용됩니다(플래그와 환경 변수가 여전히 우선).
  • 런타임 (src/i18n/index.ts): t(source, vars) 최소 버전으로 {{name}} 보간을 지원하며, 영어 소스 문자열을 키로 사용하여 src/i18n/locales/<code>.json의 평면 로케일별 번들(빌드 시 dist/i18n/locales에 복사��)과 대조합니다. 누락된 키나 번들은 소스 텍스트를 반환합니다. 이는 UI 문자열과 동일한 키-기본값 모델입니다. 해시 조회는 없습니다.
  • 대시보드: 서버는 해결된 UI 로케일에 대해 { locale, dir, bundle }을 반환하는 GET /api/ui-i18n을 노출합니다. 프론트엔드는 <html lang> / dir을 설정하고 data-i18n* 속성을 통해 정적 마크업을 지역화합니다.
  • 도그푸딩: 번들은 pnpm i18n:self(sync-ui --ui-block src/i18n/strings.json)에 의해 생성되며, 이는 ai-i18n-tools.config.json에서 CLI 및 대시보드 ui 블록을 추출하고 번역합니다. 카탈로그 키는 src/cli/ 및 src/i18n/ 전반의 t() 호출과 src/dashboard-app/index.html의 대시보드 data-i18n* 마커에서 비롯됩니다.

확장 포인트 ​

사용자 정의 함수 이름(UI 추출) ​

구성 파일을 통해 비표준 번역 함수 이름 추가:

json
{
  "ui": {
    "uiExtractor": {
      "funcNames": ["t", "i18n.t", "translate", "i18n.translate"],
      "extensions": [".js", ".jsx", ".ts", ".tsx", ".astro", ".html"],
      "htmlI18nAttributes": ["data-i18n", "data-i18n-title", "data-i18n-placeholder", "data-i18n-alt", "data-i18n-aria-label"]
    }
  }
}

(ui.reactExtractor은 ui.uiExtractor의 완전히 지원되는 별칭입니다.)

extract 중에 HTML 마커 속성을 스캔하도록 extensions에 .html / .htm을(를) 추가합니다. ui.uiExtractor.htmlI18nAttributes는 선택 사항이며 기본값은 ["data-i18n", "data-i18n-title", "data-i18n-placeholder"]입니다. data-i18n은(는) 요소 textContent에 매핑되고 data-i18n-<attr>은(는) 해당 속성의 값에 매핑됩니다(예: data-i18n-aria-label).

사용자 정의 추출기 ​

패키지에서 ContentExtractor를 구현하세요:

ts
import { BaseExtractor, type Segment } from 'ai-i18n-tools';

class MyExtractor extends BaseExtractor {
  readonly name = 'my-format';
  canHandle(filepath: string) { return filepath.endsWith('.myext'); }
  extract(content: string, filepath: string): Segment[] { /* … */ }
  reassemble(segments: Segment[], translations: Map<string, string>): string { /* … */ }
}

'ai-i18n-tools'에서 내보낸 공개 추출기 클래스를 확장하여 사용자 지정 추출기를 등록합니다(예: MarkdownExtractor 서브클래스). CLI는 내장 추출기를 내부적으로 연결합니다. doc-translate.ts의 지원되는 심층 가져오기는 없습니다.

사용자 정의 출력 경로 ​

모든 파일 레이아웃에 docsOutput.pathTemplate를 사용하세요.

json
{
  "docs": [
    {
      "docsOutput": {
        "pathTemplate": "{outputDir}/{locale}/{relativeToDocsRoot}"
      }
    }
  ]
}

소스 트리 ​

전체 src/ 레이아웃(파일 수준 참조)
text
src/
├── index.ts                        Public API re-exports
│
├── cli/
│   ├── index.ts                    CLI entry point (commander)
│   ├── extract-strings.ts          `extract` command implementation
│   ├── mark-html.ts                `mark-html` command (insert bare `data-i18n*` markers into HTML)
│   ├── translate-ui-strings.ts     `translate-ui` command implementation
│   ├── doc-translate.ts            `translate-docs` command (documentation files only)
│   ├── translate-json-run.ts       `translate-json` command (`json[]` nested locale bundles)
│   ├── translate-svg.ts            `translate-svg` command (SVG files from `config.svg`)
│   ├── write-heading-ids.ts        `write-heading-ids` command (markdown heading anchors)
│   ├── bench-models.ts             `bench-models` command (per-model translate latency/token/cost benchmark)
│   ├── helpers.ts                  Shared CLI utilities
│   └── file-utils.ts               File collection helpers
│
├── markdown/
│   └── write-heading-ids-core.ts   Slug styles + `<a id="…">` insertion for `write-heading-ids`
│
├── core/
│   ├── types.ts                    Zod schemas + TypeScript types for all config shapes
│   ├── config.ts                   Config loading, merging, validation, init templates
│   ├── cache.ts                    SQLite translation cache (node:sqlite)
│   ├── prompt-builder.ts           LLM prompt construction for docs and UI strings
│   ├── output-paths.ts             Docusaurus / flat output path resolution
│   ├── ui-languages.ts             ui-languages.json loading and locale resolution
│   ├── ui-locale.ts                Resolve the tool's own UI locale (flag/env/config/OS → shipped bundle)
│   ├── locale-utils.ts             BCP-47 normalisation, locale list parsing, script/Han-variant validation
│   └── errors.ts                   Typed error classes
│
├── extractors/
│   ├── base-extractor.ts           Abstract base class for all extractors
│   ├── ui-string-extractor.ts      JS/TS and `.astro` UI scanner (Babel via `ui-string-babel.ts`)
│   ├── ui-string-babel.ts          Babel `t()` discovery (`extractUiCallsFromFileContent`)
│   ├── ui-string-locations.ts      Source locations for extracted UI strings
│   ├── html-i18n-marks.ts          HTML `data-i18n*` marker scanner + `mark-html` annotator
│   ├── classify-segment.ts         Heuristic segment type classification
│   ├── markdown-extractor.ts       Markdown / MDX segment extraction
│   ├── markdown-segment-split.ts   Optional segment splitting for long markdown blocks
│   ├── frontmatter-fields.ts       Selective YAML front matter field translation
│   ├── astro-template-extractor.ts `.astro` parse-and-replace (HTML + template expressions; used by `translate-docs`)
│   ├── json-extractor.ts           Docusaurus catalog JSON extraction (`translate-docs`)
│   ├── nested-json-extractor.ts    Arbitrary nested JSON leaves (`translate-json`, `json[]`)
│   └── svg-extractor.ts            SVG text extraction
│
├── processors/
│   ├── placeholder-handler.ts      Chain: HTML → admonitions → anchors → MDX → URLs → emphasis
│   ├── expression-attribute-protection.ts  Shared protected attribute/key lists (Astro + MDX JSX)
│   ├── url-placeholders.ts         Markdown URL protection/restore
│   ├── admonition-placeholders.ts  Docusaurus admonition protection/restore
│   ├── anchor-placeholders.ts      HTML anchor / heading ID protection/restore
│   ├── html-tag-placeholders.ts    Lowercase HTML tag / comment protection ({{HTM_N}})
│   ├── placeholder-integrity.ts    Pre/post-restore token sequence + tag-kind + invented {{IDENT}} checks
│   ├── mdx-placeholders.ts         MDX comments, JSX tags, brace expressions, JSX attribute extraction
│   ├── batch-processor.ts          Segment → batch grouping (count + char limits)
│   ├── validator.ts                Post-translation structural checks
│   └── flat-link-rewrite.ts        Relative link rewriting for flat output
│
├── api/
│   ├── llm-client.ts               LlmClient: provider-agnostic chat client (AI SDK) with model fallback chain
│   └── provider-models-catalog.ts  Fetch/parse any provider's OpenAI-compatible GET /models catalog
│
├── glossary/
│   ├── glossary.ts                 Glossary loading (CSV + auto-build from strings.json)
│   ├── matcher.ts                  Term hint extraction for prompts
│   └── translation-context.ts      contextFiles loader and guidance fingerprints
│
├── runtime/
│   ├── index.ts                    Runtime re-exports
│   ├── template.ts                 interpolateTemplate, flipUiArrowsForRtl
│   ├── ui-language-display.ts      getUILanguageLabel, getUILanguageLabelNative
│   └── i18next-helpers.ts          RTL detection, i18next setup factories
│
├── i18n/                           Self-localisation runtime for the tool's own UI
│   ├── index.ts                    t(source, vars) + bundle/manifest loaders (keyed by English source string)
│   └── locales/                    Shipped UI bundles (de.json, es.json, …; generated by `pnpm i18n:self`)
│
├── dashboard-app/
│   ├── index.html                  Translation Dashboard static UI (HTML/CSS/JS)
│   ├── app.js
│   └── styles.css
│
├── server/
│   └── translation-dashboard.ts    Express app for Translation Dashboard (cache / strings.json / glossary)
│
└── utils/
    ├── logger.ts                   Leveled logger with ANSI support
    ├── hash.ts                     Segment hash (SHA-256 first 16 hex)
    ├── table.ts                    Display-width aware table rendering (CJK/emoji column alignment)
    ├── load-dotenv.ts              Load `.env` / `.env.local` beside the config when no API key is set
    └── ignore-parser.ts            .translate-ignore file parser

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