이중 언어 문서의 일관성 유지
공개 사용자 가이드는 상대 경로로 쌍을 이룹니다:
docs/ko/<relative-path>
docs/ja/<relative-path>
영어는 /에 게시되고, 일본어는 /ja/에 게시됩니다. 일본어는 새로운 제품 설명을 위한 실질적인 작성 원천으로 남아 있지만, 한 언어로 수정한 내용이 다른 언어에 동작, 명령어, 소유권 경계, 경고, 탐색 등의 차이를 남겨서는 안 됩니다.
범위
이 워크플로우를 두 언어 루트 아래의 index.md 및 guide/**/*.md에 적용합니다. docs/ko/reference/는 의도적으로 영어 전용입니다. 두 언어 루트 외부의 내부 아키텍처, 결정, 저장소, 기여자, 사전 테스트 문서는 번역 쌍이 아닙니다.
워크플로우
- 요청된 변경 사항과 현재 Git diff를 검사합니다. 영향을 받는 모든 공개 페이지와 동일한 상대 경로의 대응 페이지를 식별합니다.
- 두 페이지를 모두 완전히 읽습니다. 일본어 콘텐츠를 작성, 편집 또는 가독성 검토할 때는 일본어 스타일 참조도 읽습니다. 편집이 제품 동작, 명령어, 경로 또는 소유권을 변경하는 경우, 가정을 번역하는 대신 현재 소스 또는 수락된 결정을 확인합니다.
- 의미, 정보 아키텍처, 예제, 경고, 링크 대상을 유지하되, 각 대상에 대해 자연스러운 문서를 작성합니다(문장 단위 번역 금지). 의미나 정보 구조가 변경되면 두 대응 페이지를 모두 편집합니다. 일본어 전용 표현 개선의 경우 영어 대응 페이지를 검사하지만, 의미와 구조가 이미 일치하면 영어 편집을 인위적으로 만들지 않습니다.
- 대응 페이지가 없으면 생성합니다. 의도적으로 언어별 페이지인 경우 쌍 범위 밖인지 확인하거나, 지연 결정을 명시적으로 얻어 지연 사유와 추적 위치를 보고합니다. 이중 언어 변경이 언급되지 않은 채 완료되지 않도록 합니다.
- 이동 또는 삭제의 경우 동일한 상대 경로 변경을 두 트리에 적용하고
mkdocs.yml, 인바운드 링크, 기여자 안내, 코드나 테스트에 포함된 공개 URL을 업데이트합니다.
검증
저장소 루트에서 다음을 실행합니다:
python -m mkdocs build --strict
git diff --check
생성된 영어와 일본어 페이지가 대응 경로에 존재하고, 언어 선택기 링크가 서로를 가리키는지 확인합니다. 공개 URL이 CLI 계약인 경우 소스, 집중 테스트, 수락된 결정도 업데이트한 후 집중 테스트와 python scripts/check_decisions.py를 실행합니다.
검사하고 변경한 페이지 쌍, 의미 비교 후 의도적으로 변경하지 않은 대응 페이지, 기타 예외, 검증 결과를 보고합니다.