- 현재: KO → EN 자동 번역이 v1 API 폴더(
docs/src/content/docs/ko/v1/api/**)만 대상임.
- 변경 목표:
- 전체 문서를 번역 대상으로 확대 (api 외 getting-started, manual-setup, user-manual, v1/guides, plan, reference, archive 등).
- 이미 번역된 페이지는 원본(KO) 파일에 변경이 없으면 재번역하지 않는 로직이 있는지 확인하고, 없으면 추가한다.
| 구분 | 경로 | 비고 |
|---|
| 워크플로 트리거 | docs/src/content/docs/ko/v1/api/**/*.md | push 시 이 경로만 감지 |
| 스크립트 기본 발견 | --only-v1-api 시 src/v1/api/ 하위만 | 파일 인자 없을 때 |
| 이미 EN 존재 | getting-started, manual-setup, index, changelog, v1/api 5개 등 | 나머지 ko 문서는 EN 미생성 |
- Push 시:
git diff --name-only ${{ github.event.before }} ${{ github.sha }} 로 변경된 KO 파일 목록만 추출한 뒤, 그 목록만 스크립트에 인자로 전달.
- 결과: “변경된 파일만 번역”은 워크플로 단에서 이뤄짐. 즉, 원본이 변경되지 않은 파일은 아예 스크립트에 넘어오지 않음 (현재는 v1/api 한정).
- 한계: 수동 실행(workflow_dispatch) 시에는 v1/api 하위 전부를 인자로 넘기므로, 원본이 바뀌지 않은 파일도 스크립트에서 다시 처리됨.
- 있는 로직:
--incremental: EN 파일이 있으면 기존 ## 섹션은 유지하고, 새로 추가된 섹션만 번역. (기존 섹션은 DeepL 호출 안 함.)- DeepL이 원문과 동일한 문자열을 반환하면 해당 파일은 쓰지 않음 (
[skip] translation identical to source).
- 없는 로직:
- “KO 원본 내용이 지난 번역 이후로 바뀌지 않았으면 이 파일은 아예 스킵” 하는 처리 없음.
- 즉, EN frontmatter나 별도 메타데이터에 “이 EN을 만들 때 사용한 KO 원본의 해시”를 저장하고, 실행 시 KO 해시를 계산해 비교하는 스킵 조건이 없음.
| 계층 | ”변경 없으면 재번역 안 함” 유무 | 비고 |
|---|
| 워크플로 (push) | 있음 (간접) | 변경된 파일만 스크립트에 전달 → 변경 없는 파일은 처리 대상 아님 |
| 워크플로 (수동) | 없음 | v1/api 전체를 넘기면 변경 없는 파일도 스크립트에서 다시 처리 |
| 스크립트 | 없음 | KO 원본 해시 저장·비교로 “원본 미변경 시 스킵” 하지 않음 |
따라서 스크립트 단에 “원본 미변경 시 재번역 스킵” 로직을 추가하는 것이 필요하다.
(수동 전체 실행 시 API 호출·쓰기 절감, 그리고 향후 “전체 문서” 확대 시 push에서도 변경된 파일만 넘기더라도, 스크립트가 해시 기반 스킵을 하면 일관된 동작이 됨.)
- 대상 디렉터리:
docs/src/content/docs/ko/ 하위 전체 .md (단, 제외 목록은 아래 참고).
- 제외 후보 (선택 적용):
ko/plan/ 등 내부 기획/노트만 있는 폴더ko/archive/ 등 과거 아카이브- 특정 파일:
PLAN_CONSOLIDATION_MASTER_TABLE.md 등
- 워크플로:
on.push.paths: docs/src/content/docs/ko/v1/api/** → docs/src/content/docs/ko/** (또는 제외를 반영한 경로)로 확대.- “Get changed KO doc files” 단계:
git diff 대상도 동일하게 ko/**/*.md 전체로 변경.
- 수동 실행 시: v1/api만이 아니라 전체 KO 문서 목록을 넘기거나,
--only-v1-api 제거 후 src_root.rglob("*.md") 등으로 전체 발견.
- 스크립트:
--only-v1-api 옵션은 유지하되, 기본값 또는 수동 실행 시에는 전체 발견 모드 사용 (또는 --all-docs 플래그 추가).- 제외 목록은 인자(예:
--exclude plan,archive) 또는 설정 파일로 지정 가능하게 할지 검토.
- 목표: 이미 EN이 있고, 해당 EN을 생성할 때 사용한 KO 원본 내용이 현재 KO와 동일하면 DeepL 호출 및 파일 쓰기를 하지 않는다.
- 방식 (권장):
- 원본 해시 저장: 번역 결과(EN)를 쓸 때, 사용한 KO 본문(또는 전체 원문) 의 해시(SHA-256 등)를 EN frontmatter에 저장.
예: translatedFromHash: "abc123..." (또는 translated_from_ko_sha256).
- 실행 시 스킵 조건:
- EN 파일이 존재하고,
- EN frontmatter에
translatedFromHash가 있고,
- 현재 KO 파일 내용의 동일 규칙으로 계산한 해시가 저장된 값과 같으면
- 해당 파일은 번역 함수 진입 전에 스킵 (로그만 남기고 다음 파일로).
- 해시 대상: KO 파일 전체 또는 frontmatter 제외 본문만 중 하나로 통일. (본문만 쓰면 frontmatter만 바뀐 경우 재번역됨.)
- 기존 EN: 이미
translatedFromHash가 없는 EN은 “없음”으로 간주하고, 해시 비교 시 “같다”로 처리하지 않음 → 기존처럼 번역 수행 후 새로 해시 저장.
- 부수 효과:
- 수동 “전체 번역” 실행 시 변경 없는 파일은 API 호출·디스크 쓰기 제거.
- Push 시에도 (변경된 파일만 넘어오므로) 스크립트 입장에서는 적은 수만 처리하지만, 향후 다른 트리거에서 전체 목록을 넘길 때 스킵 로직이 유효.
| 항목 | 현재 | 변경 후 |
|---|
on.push.paths | ko/v1/api/**/*.md | ko/**/*.md (또는 제외 반영) |
| 변경 파일 수집 경로 | API_ROOT=".../ko/v1/api" | DOCS_ROOT=".../ko" 및 **/*.md |
| 수동 실행 시 파일 목록 | v1/api 하위 전체 | 전체 KO .md (또는 --all-docs에 해당하는 목록) |
| 워크플로 이름/설명 | ”v1 API only" | "KO to EN (all docs)” 등으로 수정 |
| 항목 | 내용 |
|---|
| 해시 저장 | translate_file() 성공 시 EN frontmatter에 translatedFromHash 기록 (KO 원본 해시). |
| 스킵 조건 | EN 존재 + frontmatter에 해시 있음 + 현재 KO 해시 == 저장 해시 → 번역/쓰기 생략, 로그만 출력. |
| CLI | 필요 시 --skip-unchanged 플래그 추가 (기본 True). 해시 없으면 스킵 안 함. |
| 번역 대상 발견 | --only-v1-api 없이 파일 인자 없을 때 src_root.rglob("*.md") 또는 --all-docs 시 전체, 제외 목록 적용. |
docs/src/content/docs/ko/user-manual/translation-pipeline.md:
- “번역 대상: v1 API 만” → “번역 대상: 전체 문서 (또는 제외 목록 명시)”.
- “변경 없으면 재번역 안 함” 동작 설명 추가 (frontmatter 해시 기반 스킵).
- 워크플로 이름이 바뀌면 해당 워크플로 설명/스크린샷 등도 수정.
- 전체 문서 번역 확대 후: ko 하위 대표 경로(getting-started, user-manual, v1/guides 일부, plan 일부 등)에 대해 EN이 생성되는지, 빌드가 깨지지 않는지 확인.
- 스킵 로직: KO 파일을 수정하지 않고 수동으로 “전체 번역” 실행 → 이미 번역된 파일은
[skip] source unchanged 등 로그만 나오고 DeepL 호출/쓰기가 없음을 확인.
- 기존 EN 호환:
translatedFromHash가 없는 기존 EN 파일은 그대로 재번역 가능하고, 실행 후 frontmatter에 해시가 붙는지 확인.
- 번역 범위: API 섹션만 → 전체 문서로 확대 (제외 목록 선택 적용).
- “변경 없으면 재번역 안 함”:
- 워크플로: push 시에는 이미 “변경된 파일만” 넘김.
- 스크립트: 현재 없음 → EN frontmatter에 KO 원본 해시 저장 + 실행 시 비교하여 동일하면 스킵하는 로직을 추가하는 것이 기획안에 포함됨.
이 기획서를 바탕으로 구현 단계(워크플로 YAML 수정, translate_docs.py 수정, 번역 파이프라인 문서 수정)를 진행하면 된다.