국제화 및 기계 번역¶
문서는 영어와 간체 중국어를 검토된 표준 출처로 간주합니다. 다른 모든 활성화된 언어는 자동 생성된
파생물입니다. 언어 레지스트리, 소스 라우팅, 모델 구성 및 API 제한은
i18n/config.toml에 있습니다.
1. 언어 범위 및 소스 라우팅¶
레지스트리는 의도적으로 범위를 12개 사이트 언어로 수렴합니다. 여기에는 유엔 6개 공식 언어인 아랍어, 중국어, 영어, 프랑스어, 러시아어, 스페인어가 포함됩니다. 동아시아 지역에는 일본어, 한국어, 번체 중국어가 추가로 포함되고, 유럽 지역에는 독일어, 이탈리아어, 포르투갈어가 추가로 포함됩니다. 영어와 간체 중국어는 표준 출처이므로 총 10개 언어가 기계 번역됩니다.
일본어, 한국어, 번체 중국어는 간체 중국어를 소스로 사용합니다. 다른 모든 파생 언어는 영어를 소스로 사용합니다. 각 언어의 소스는 구성에 명시적으로 지정되며, 번역기는 언어 이름이나 문서 문자를 기반으로 추측하지 않습니다.
새 언어를 추가할 때는 i18n/config.toml와 MkDocs i18n 언어 목록을 모두 업데이트해야 합니다. 문서
감사는 두 레지스트리가 일치하지 않는 상태를 거부합니다.
2. 표준 문서 계약¶
각 MkDocs 페이지에는 영어 파일과 .zh-CN.md 파일이 모두 있어야 합니다. Pull request,
main에 대한 푸시 또는 수동으로 트리거된 품질 검사가 표준 버전 중 하나를 수정하는 경우
검사된 커밋 범위 내에 다른 버전도 포함해야 합니다. 품질 워크플로는 다음을 확인합니다.
- 표준 문서 쌍 및 변경 쌍;
- 제목 수준과 코드 펜스의 일관성;
- 로컬 링크 및 소스 참조;
- fixture 및 테스트 매니페스트;
- 모든 구성된 언어에 대한 엄격한 빌드.
표준 콘텐츠는 사람이 작성하거나 AI를 사용할 수 있지만 일반 소스 코드로 제출되고 검토되어야 합니다. Pull request 워크플로는 절대 번역 API를 호출하지 않습니다.
3. 제목 번호 및 조각 링크 안정성¶
Markdown 소스 문서는 설명적인 제목 텍스트만 저장하고 개요 번호는 저장하지 않습니다. 각 MkDocs 빌드 시
scripts/mkdocs_heading_numbers.py는 H2–H6에 페이지 내 번호를 추가합니다. 사용 가이드 페이지
의 H2는 소문자(a., b.)를 사용하고, 더 깊은 수준은 문자와 십진수(a.1,
a.1.1)를 사용합니다. 다른 페이지는 여전히 십진수 페이지 개요를 사용합니다. 왼쪽 사용 가이드 탐색은 별도로
1.1과 같은 계층적 십진수 번호를 사용합니다. H1 페이지 제목과 최상위 탐색 열은 번호가 매겨지지 않습니다. 생성된 번호는
표시 메타데이터입니다. 섹션을 이동하면 표시되는 번호는 변경되지만 조각 식별자는 변경되지 않습니다.
빌드 후크는 먼저 각 제목의 명시적 식별자를 고정한 다음 표시 번호를 추가합니다.
i18n/legacy-heading-anchors.json는 수동 번호가 제거되기 전에 게시된 조각 별칭을 유지합니다.
이 생성된 호환성 매핑을 편집하지 말고 표준 또는 파생 Markdown에 수동
개요 번호를 다시 추가하지 마십시오. 문서 감사는 이러한 콘텐츠를 거부합니다.
4. 파생 문서 계약¶
생성된 페이지는 MkDocs 접미사 패턴을 사용합니다(예: index.fr.md 또는
guide/configuration.ja.md). 각 페이지에는 다음을 기록하는 결정적 front matter가 포함됩니다.
- 표준 소스 언어 및 경로;
- 소스 파일의 SHA-256 다이제스트;
- 실제 사용된 모델 및 프롬프트 버전;
- 해당 페이지가 기계 번역되었음.
i18n/manifest.json는 또한 출력 다이제스트와 번역 입력 지문을 기록합니다. 소스, 용어집, 프롬프트,
모델 또는 생성된 출력이 변경되면 페이지가 만료된 것으로 간주됩니다. 명시적으로 전체 재구축이 요청되지 않는 한 번역기는
만료된 단위만 요청합니다.
번역된 제목은 지역화된 자연스러운 slug를 유지하면서 표준 소스 slug의 숨겨진 별칭을 얻습니다. Markdown 링크 대상은 다른 경우 보호되어 모델이 수정할 수 없으므로 이러한 별칭은 동일 페이지 및 교차 페이지 조각 링크가 모든 언어에서 유효하도록 보장합니다. 별칭은 번역 API를 다시 호출하지 않고 오프라인에서 새로 고칠 수 있습니다.
생성된 파일은 수동으로 편집해서는 안 됩니다. 메인 브랜치 번역 워크플로는 이러한 파일을 다시 생성하고 각 언어가 완료된 후
해당 언어를 품질 검사 정확한 SHA에서 파생된 generated-only 브랜치에 단일 배치로 커밋합니다.
후속 실행은 먼저 해당 브랜치를 확인한 후 재사용하므로 중단 시 처리 중인 언어만 손실됩니다. 워크플로가
파생 언어 감사, 전체 테스트 스위트 및 모든 언어에 대한 엄격한 빌드를 완료할 때까지 main는 변경되지 않습니다.
모든 검증이 통과되면 워크플로는 main가 진행되지 않았음을 다시 확인하고, fast-forward 푸시로 checkpoint를
올린 다음 동일하게 검증된 사이트 아티팩트를 배포합니다.
5. Markdown 보호 및 프롬프트 계약¶
API 요청을 보내기 전에 번역기는 front matter, 펜스 코드, 인라인 코드, 링크 대상, HTML 태그 및 일반 URL을 변경할 수 없는 자리 표시자로 대체합니다. 자리 표시자가 누락, 중복, 갑자기 나타나거나 계약에 따라 복원할 수 없는 경우 응답이 거부됩니다.
프롬프트는 또한 제목 수준과 코드 펜스 언어가 일관되도록 요구합니다. 구현은 보호된 콘텐츠를 복원한 후 이러한 속성을 독립적으로 확인합니다. 번역 출력은 JSON 객체여야 합니다. JSON 외부의 설명 텍스트, 빈 콘텐츠, 비정상 종료 이유 또는 호환되지 않는 데이터 구조는 모두 실패입니다.
Markdown 및 탐색 목차 프롬프트는 i18n/prompts/에서 별도로 버전 관리됩니다.
i18n/glossary.json는 안정적인 제품 이름 및 명령 용어를 저장합니다.
6. 모델 구성 및 자격 증명¶
기본 모델 구성은 deepseek-v4-flash입니다. 구현은 이 이름에 대한 조건부 분기를 작성하지 않습니다. 나중에
모델을 변경할 때는 i18n/config.toml를 수정하고, --model를 전달하거나,
DEEPSEEK_TRANSLATION_MODEL 워크플로 변수를 설정하기만 하면 됩니다. 최종 확인된 모델은 각 생성된
페이지 및 매니페스트 항목에 기록됩니다.
GitHub Actions는 DEEKSEEK_API_KEY라는 repository secret에서만 API
자격 증명을 읽습니다. 오프라인 계획에서 처리해야 할 API 번역 단위가 있는 것으로 표시된 경우에만 생성 단계가 해당
secret에 액세스합니다. 신뢰할 수 없는 pull request 코드와 API가 필요 없는 계획, 정리 및 확인 단계는 액세스할 수
없습니다. 인증 값은 로그, 생성된 파일, 아티팩트 또는 매니페스트에 절대 기록되지 않습니다.
7. 페이지 프롬프트 및 언어 기본 설정¶
기계 생성 페이지는 렌더링 시 지역화된 경고를 받습니다. 이 경고는 페이지가 AI로 번역되었음을 설명하고, 권위 있는 영어 또는 간체 중국어 원본에 대한 링크와 미리 채워진 번역 문제 보고서에 대한 링크를 제공합니다. 프롬프트는 번역된 Markdown에 속하지 않으며 목차 항목을 생성하지 않습니다.
방문자가 처음으로 사이트 루트 페이지를 열면 사이트는 navigator.languages를 이미 구성된
언어 옵션과 비교하고 호환되는 항목이 있으면 해당 언어를 선택합니다. 사용자가 수동으로 선택한 언어는
로컬에 저장되며 이후 방문 시 우선 적용됩니다.
8. 유지 관리 명령¶
네트워크 요청 없이 번역 대기 중인 단위 수를 확인하려면:
uv run python scripts/translate_docs.py --plan
모든 생성된 페이지와 목차 번역이 최신 상태인지 확인하려면:
uv run python scripts/translate_docs.py --check
uv run python scripts/audit_docs.py --machine-mode required
API를 호출하지 않고 안정적인 소스 제목 별칭을 새로 고치려면:
uv run python scripts/translate_docs.py --refresh-heading-anchors
명시적 모델을 사용하여 전체 재구축을 강제하려면:
DEEKSEEK_API_KEY=... uv run python scripts/translate_docs.py \
--force --model deepseek-v4-flash
자동 워크플로는 repository secret을 사용하며 명령줄에 키를 두지 않습니다.