Skip to content

문서 ​

translate-docs는 docs[] 구성 블록에 나열된 Markdown, MDX, .astro 및 일반 HTML 페이지용 파이프라인에 대한 참조입니다. 각 블록의 contentPaths 필드에는 번역할 파일 또는 폴더가 나열됩니다. 이 파일들은 sourceLocale로 작성되며, 어떤 언어든 될 수 있습니다. 예제의 영어는 샘플일 뿐입니다. 사이트에 처음으로 언어를 추가하시나요? 웹사이트 또는 문서 사이트에 i18n 추가에서 시작하세요. 리포지토리 README 및 일반적으로 앱과 함께 있는 기타 Markdown 파일의 경우: README 및 Markdown 문서에 i18n 추가. 일반 HTML 페이지(로케일당 하나의 파일)는 HTML 페이지에 설명되어 있습니다.

프레임워크 셸 문자열(탐색 모음, 사이드바, 테마)은 별도의 파이프라인이 아닌 동일한 실행에서 번역됩니다. 아래 표의 프레임워크 가이드에서 각각의 방법을 설명합니다. Docusaurus는 docusaurusCatalogDir, VitePress는 docsOutput.vitepressThemeCatalog, Nextra는 docs[].nextraDictionaryPath, Fumadocs는 docsOutput.fumadocsUiCatalog입니다. Nextra _meta.ts 및 Fumadocs meta.json 사이드바 레이블은 자동으로 수집됩니다. Astro Starlight는 많은 로케일에 대한 내장 UI 문자열을 제공하며, 선택적 재정의는 docs[] 블록에서 jsonPathTemplate을 사용할 수 있습니다.

마크다운에 포함된 PNG 및 기타 래스터 이미지에 대해서는 이미지 및 스크린샷을 참조하십시오. translate-docs는 alt 텍스트만 번역하며 래스터 파일을 복사하지 않습니다.

README나 문서에서 선택적 언어 전환기 블록을 사용하려면 docsOutput.style를 "flat"로 설정하세요 — 언어 전환기를 참조하세요.

SVG 파일은 features.translateSVG가 활성화된 경우 translate-svg를 통해 번역됩니다 — docs[] / contentPaths를 통하지 않습니다.

문서 프레임워크의 셸/테마 문자열과 관련 없는 임의의 중첩된 UI JSON 번들은 docs[]이 아닌 JSON 파이프라인에 속합니다.

각 UI 블록은 기본적으로 문서용 용어집 힌트로 strings.json을(를) 포함합니다(uiGlossary, 기본값 true). translate-docs은(는) 세그먼트에 일치하는 용어가 나타날 때 LLM 프롬프트의 힌트로 해당 번역을 재사용합니다. 문서 프롬프트에서 제외해야 하는 카탈로그의 uiGlossary을(를) false(으)로 설정합니다. 선택 사항인 glossary.userGlossary은(는) 제품 용어에 대한 CSV 재정의를 추가합니다(translate-ui 및 proofread-ui과(와) 공유됨). 좁은 열에 맞추기 위해 사용되는 간결한 UI 레이블 약어(예: Size → Tam)는 UI 번역에는 계속 사용할 수 있지만 문서 용어집 힌트에서는 제외됩니다. glossary-generate을(를) 사용하여 시작 CSV를 생성하고, 번역 대시보드의 용어집 탭에서 행을 편집하거나, 구성 — glossary 및 용어집을(를) 참조하십시오.

로케일별 모델 재정의 ​

translate-docs 및 sync의 문서 단계는 대상 로케일별로 모델을 확인합니다. 구성된 경우 localeModels(locale)를 먼저 확인하고, 그 다음 공급자의 전역 translationModels 체인을 확인합니다. 특정 언어에 기본 대체 목록과 다른 모델이 필요한 경우 이 기능을 사용하세요. 예를 들어 전역 체인이 포르투갈어를 처리하는 데 어려움을 겪을 때 pt-BR 문서에 Gemini를 선호하는 경우입니다. AI 모델 및 구성 - localeModels을 참조하세요.

어떤 가이드를 읽어야 할까요? ​

설정시작하기
Docusaurus 사이트init -t ui-docusaurus, docsOutput.style = "docusaurus" - Docusaurus
VitePress 사이트테마용 init -t ui-vitepress + vitepressThemeCatalog - VitePress
Nextra 사이트사전용 init -t ui-nextra + nextraDictionaryPath (sidebar _meta.ts는 자동) - Nextra
Fumadocs 사이트UI용 init -t ui-fumadocs + fumadocsUiCatalog (sidebar meta.json는 자동) - Fumadocs
Astro Starlightinit -t ui-starlight - Astro Starlight
일반 HTML 페이지init -t docs-plain-html - HTML 페이지
플랫 문서(README, 변경 로그 등)README 및 Markdown 문서에 i18n 추가 — init -t docs-markdown 또는 --with-readme. 레이아웃: 출력 레이아웃, 언어 전환기
번역된 파일이 저장되는 위치출력 레이아웃
페이지 간 #anchor 링크앵커 링크
링크 및 애셋 URL 재작성(regexAdjustments)링크 재작성
문서의 스크린샷이미지 및 스크린샷
제품 용어 및 UI/문서 일관성구성 — glossary, 용어집
translate-docs 플래그 및 캐시CLI 옵션

1단계: 문서 초기화 ​

bash
ai-i18n-tools init -t ui-docusaurus -P openai

Astro Starlight 문서 사이트의 경우:

bash
ai-i18n-tools init -t ui-starlight -P cheaperinference

VitePress 문서 사이트의 경우:

bash
ai-i18n-tools init -t ui-vitepress -P anthropic

nav/sidebar/footer 문자열에 대해 docsOutput.vitepressThemeCatalog를 설정하세요 — VitePress 통합을 참조하세요.

Nextra 문서 사이트의 경우:

bash
ai-i18n-tools init -t ui-nextra -P gemini

테마 사전 문자열에 대해 docs[].nextraDictionaryPath를 설정하세요 — Nextra 통합을 참조하세요. Sidebar _meta.ts 레이블은 자동으로 수집됩니다.

Fumadocs 문서 사이트의 경우:

bash
ai-i18n-tools init -t ui-fumadocs -P groq

UI 재정의에 대해 docsOutput.fumadocsUiCatalog를 설정하세요 — Fumadocs 통합을 참조하세요. Sidebar meta.json 레이블은 자동으로 수집됩니다.

일반 Astro 웹사이트 UI(스타라이트 없음)의 경우:

bash
ai-i18n-tools init -t ui-astro-website -P ollama

해당 템플릿은 UI 추출만 활성화합니다. 페이지 HTML을 번역하려면 features.translateDocs을 설정하고 docs[] 블록을 추가하세요(Astro 웹사이트 페이지(구문 분석 및 바꾸기) 참조). examples/astro-website 구성은 두 파이프라인을 함께 보여줍니다.

생성된 ai-i18n-tools.config.json을 편집하세요:

  • provider 및 providers — init -P <provider>는 해당 사전 설정을 스캐폴딩합니다. translate-docs 또는 sync 전에 API 키를 설정하세요(Ollama는 키가 필요하지 않습니다). 공급자 및 API 키, LLM 공급자, AI 모델을 참조하세요.
  • sourceLocale - 소스 언어(docusaurus.config.js의 defaultLocale와 일치해야 함).
  • targetLocales - BCP-47 로케일 코드 배열(예: ["de", "fr", "es"]).
  • cacheDir - 모든 파이프라인에 대한 공유 SQLite 캐시 디렉터리(--write-logs의 기본 로그 디렉터리).
  • docs - 문서 블록 배열. 각 블록에는 선택적 description, contentPaths(문자열 또는 배열; 파일, 디렉터리 또는 glob), outputDir, 선택적 docusaurusCatalogDir, docsOutput, 선택적 segmentSplitting, translateFrontmatterFields, protectAttributes, protectKeys, targetLocales, addFrontmatter 등이 있습니다.
  • docs[].description - 유지 관리자를 위한 선택적 짧은 메모. 설정하면 translate-docs 헤드라인과 status 섹션 헤더에 나타납니다.
  • docs[].contentPaths - markdown/MDX/.astro 소스(및 Docusaurus 셸 JSON을 위한 선택적 docusaurusCatalogDir).
  • docs[].outputDir - 해당 블록의 번역된 출력 루트.
  • docs[].docsOutput.style - "nested"(기본값), "flat", "doc-system" 또는 별칭 "docusaurus" / "astro-starlight" / "vitepress" / "nextra" / "fumadocs"(출력 레이아웃 참조).
  • ui[].uiGlossary - true(기본값)인 경우, 해당 블록의 strings.json이(가) 문서 세그먼트에 대한 용어 힌트를 제공합니다(구성 — ui 참조).
  • glossary.userGlossary - 고정된 제품 용어 번역을 위한 선택적 CSV로, UI 파이프라인에서도 사용되며 용어집 대시보드 탭에서 편집할 수 있습니다.

주요 vs 보조: 로컬화된 페이지에 대해 contentPaths에 집중하십시오. docusaurusCatalogDir을 설정하면 write-translations에서 Docusaurus 셸 JSON도 필요할 때입니다. 페이지만 번역하는 경우 docusaurusCatalogDir는 생략하십시오.

2단계: 문서 번역 ​

bash
ai-i18n-tools translate-docs

이것은 모든 docs[] 블록의 contentPaths(및 docusaurusCatalogDir가 설정된 경우 Docusaurus 카탈로그 JSON)에 있는 모든 파일을 모든 유효한 문서 로케일로 번역합니다. 이미 번역된 세그먼트는 SQLite 캐시에서 제공되며 - 새롭거나 변경된 세그먼트만 LLM으로 전송됩니다.

단일 로케일을 번역하려면:

bash
ai-i18n-tools translate-docs --locale de

번역이 필요한 항목을 확인하려면:

bash
ai-i18n-tools status

플래그, 캐시 동작 및 배치 프롬프트 형식에 대한 자세한 내용은 CLI 옵션을 참조하십시오.

복잡한 마크다운 및 품질 검사 실패 ​

translate-docs는 각 번역된 세그먼트가 마크다운 구조(문서에서 파싱된 강조 포함)를 유지하고 내부 플레이스홀더 토큰이 깔끔하게 복원되는지 확인합니다. `inline code` 주변에 여러 bold 스팬을 쌓거나, 굵게 안에 백틱을 중첩하거나(예: `fetch(\`/locales/${code}.json\`)`와 같은 템플릿 리터럴), 하나의 긴 문장에 굵게와 코드를 엮는 단락은 취약합니다. 일부 로캘은 다른 어순이 필요하므로, 번역 후 ** 및 `가 정렬되는 방식이 변경되어 AST mismatch과 같은 CLI 오류가 발생할 수 있습니다.

복원 후, translate-docs는 HTML 태그 플레이스홀더가 재사용되거나 누락된 세그먼트(따라서 복원된 태그가 소스 맵과 더 이상 일치하지 않음) 또는 모델이 소스에 없는 이중 중괄호 토큰(예: 가짜 용어집 스타일 토큰)을 임의로 생성한 세그먼트도 거부합니다. 복원 전 검사에는 동일한 {{…}} 토큰의 다중 집합과 동일한 순서의 구조적 토큰 하위 시퀀스({{HTM_N}}, admonition 마커)가 필요합니다. {{ILC_N}}, {{URL_N}}와 같은 콘텐츠 토큰 및 {{SE}}와 같은 강조 마커는 각 ID/유형 수가 여전히 일치하는 한 자연스러운 어순에 따라 이동할 수 있습니다. 이러한 실패는 남은 공식 내부 토큰과 동일한 모델 폴백 경로를 사용합니다.

이러한 종류의 유효성 검사 실패가 발생하면, 소스 언어 텍스트를 단순화하는 것을 선호하십시오 - 단락을 분할하거나, 예제를 펜스 코드 블록으로 이동하거나, 겹겨진 굵게/코드 쌍을 줄여 동일한 아이디어를 설명하십시오 - 모든 모델과 로케일이 조밀한 인라인 마크업을 완벽하게 재현할 것으로 기대하지 마십시오.

세그먼트에 대해 시도된 모델이 AST mismatch 오류로 실패하면, translate-docs은 해당 세그먼트를 더 작은 부분으로 자동 분할하고 (먼저 목록 중간 지점, 그 다음 단일 목록 항목 또는 더 짧은 단락 청크), 첫 번째 모델부터 각 부분을 재시도하며, 결과를 원래 세그먼트 캐시 키 아래에서 다시 결합할 수 있습니다. 동일한 품질 오류가 세 번 발생하면 모델 목록이 조기에 중단되고, 다른 오류는 계속 진행됩니다. 이 기능은 기본적으로 켜져 있으며 (segmentSplitting.qualityRetrySplit), 모델 목록이 끝난 후 중지하려면 false으로 설정하십시오. 이 대체 기능이 실행될 때 실행 요약에 Quality split retries가 보고됩니다.

어떤 세그먼트가 실패했는지, 얼마나 자주 실패했는지, 저장된 품질/오류 메시지를 확인하려면 번역 대시보드의 실패 탭(번역 대시보드 → 실패)을 사용하십시오.

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