문서 번역하기

기능

tyndale translate-docs는 기본 언어의 원본 문서를 tyndale.config.json의 모든 로캘로 번역합니다.

이 기능은 앱 UI 문자열이 아니라 문서 사이트를 위해 설계되었습니다:

• 원본 문서 디렉터리에서 Markdown 및 MDX 문서를 읽습니다
• 문서 프레임워크의 규칙에 맞춰 번역된 파일을 작성합니다
• 이미 최신 상태인 파일은 건너뜁니다
• 생성된 문서를 검증하고, 실패를 보고하기 전에 잘못된 출력은 자동으로 재시도합니다

tyndale translate에 사용하는 것과 동일한 AI provider 설정을 사용하세요.

지원되는 프레임워크

현재 translate-docs는 다음을 지원합니다:

• Starlight
• Docusaurus
• VitePress
• MkDocs
• Nextra

빠른 시작

npx tyndale translate-docs setup
npx tyndale translate-docs

translate-docs setup은 현재 프로젝트에서 지원되는 문서 프레임워크를 감지하고 tyndale.config.json에 docs 블록을 작성합니다.

그런 다음 translate-docs는 해당 설정을 사용해 영어 원본 문서를 찾고, 프레임워크에 맞는 올바른 위치에 번역 문서를 작성합니다.

예상 설정

기존 Tyndale 설정은 유지하고, docs 블록만 추가하세요:

{
  "defaultLocale": "en",
  "locales": ["es", "fr", "ja"],
  "docs": {
    "framework": "starlight",
    "contentDir": "src/content/docs"
  }
}

docs.framework는 다음 중 하나여야 합니다:

• starlight
• docusaurus
• vitepress
• mkdocs
• nextra

docs.contentDir는 기본 언어의 원본 문서 디렉터리를 가리킵니다.

참고:

• defaultLocale는 locales에 포함되면 안 됩니다
• translate-docs는 프레임워크별 파일 확장자를 자동으로 사용합니다
• --content-dir는 실행 시 설정된 문서 디렉터리를 덮어씁니다

setup 감지 방식

npx tyndale translate-docs setup은 현재 프로젝트에서 지원되는 프레임워크를 스캔합니다.

감지는 다음과 같은 프레임워크별 신호를 기반으로 합니다:

• 설치된 패키지 의존성
• 알려진 프레임워크 설정 파일

현재 기본값은 다음과 같습니다:

• Starlight → src/content/docs
• Docusaurus → docs
• VitePress → docs
• MkDocs → docs
• Nextra → pages

MkDocs의 경우 mkdocs.yml 또는 mkdocs.yaml 파일만 있어도 높은 신뢰도로 감지할 수 있습니다.

setup이 여러 후보를 찾으면, 첫 번째 고신뢰 일치 항목을 우선 선택합니다. 이후 선택된 프레임워크와 콘텐츠 디렉터리를 tyndale.config.json에 기록합니다.

setup을 건너뛰더라도, translate-docs는 한 가지 제한된 경우에는 자동 감지를 할 수 있습니다: 고신뢰 프레임워크를 정확히 하나만 찾았을 때입니다. 그 외에는 --content-dir를 전달하지 않으면 src/content/docs로 대체됩니다.

증분 동작

translate-docs는 프로젝트 루트에 증분 상태 파일을 유지합니다:

.tyndale-docs-state.json

각 로캘과 원본 파일에 대해, Tyndale은 현재 원본 문서의 해시를 저장합니다. 다음 실행에서는 아래 경우에만 문서를 다시 번역합니다:

• 번역 대상 파일이 없는 경우
• 영어 원본 파일이 변경된 경우
• --force를 전달한 경우

즉, 일반 실행에서는 누락되었거나 변경된 문서만 처리합니다.

전체 문서를 다시 번역하려면:

npx tyndale translate-docs --force

번역 파일이 저장되는 위치

Tyndale은 선택한 프레임워크에 따라 번역 문서를 작성합니다.

Starlight

원본 문서는 src/content/docs에 그대로 유지되고, 번역 문서는 해당 디렉터리 아래 로캘 폴더에 저장됩니다:

src/content/docs/getting-started.mdx
src/content/docs/es/getting-started.mdx
src/content/docs/fr/getting-started.mdx

VitePress and MkDocs

이 둘은 문서 디렉터리 내부에서 로캘별 폴더를 사용하는 동일한 규칙을 따릅니다:

docs/guide.md
docs/es/guide.md
docs/fr/guide.md

Docusaurus

Docusaurus 번역은 해당 i18n 문서 구조에 기록됩니다:

docs/intro.mdx
i18n/es/docusaurus-plugin-content-docs/current/intro.mdx
i18n/fr/docusaurus-plugin-content-docs/current/intro.mdx

Nextra

Nextra는 원본 파일 옆에 로캘 접미사를 붙여 번역 파일을 작성합니다:

pages/docs/getting-started.mdx
pages/docs/getting-started.es.mdx
pages/docs/getting-started.fr.mdx

Starlight 예시

이 저장소는 Starlight를 사용하므로, 일반적인 설정은 다음과 같습니다:

{
  "defaultLocale": "en",
  "locales": ["de", "es", "fr", "it", "ja", "ko", "pt", "ru", "zh"],
  "docs": {
    "framework": "starlight",
    "contentDir": "src/content/docs"
  }
}

그다음 실행:

npx tyndale translate-docs

Tyndale은 src/content/docs에서 영어 문서를 읽고, src/content/docs/es/, src/content/docs/fr/ 같은 로캘 폴더에 번역 문서를 작성합니다.

CLI 옵션

npx tyndale translate-docs --content-dir docs --concurrency 4

현재 옵션은 다음과 같습니다:

• 문서 원본 디렉터리를 덮어쓰려면 --content-dir <path>
• 병렬 번역 세션 수를 제어하려면 --concurrency <n>
• 모든 문서를 다시 번역하려면 --force

검증되는 항목

각 번역 후, Tyndale은 생성된 문서를 유지하기 전에 검사합니다. 크게 보면, 결과가 여전히 유효한 문서 파일처럼 보이는지 확인합니다:

• frontmatter가 여전히 존재하고 사용 가능한지
• title 같은 필수 메타데이터가 여전히 존재하는지
• 원본 import 라인이 보존되었는지
• 모델이 전체 파일을 코드 펜스로 감싸지 않았는지

생성 파일이 검증에 실패하면, Tyndale은 모델에 수정을 요청하고 자동으로 재시도합니다. 계속 실패하는 파일은 실행 마지막에 보고됩니다.