문서 번역 재고: 번역을 버전 관리되는 소프트웨어 자산으로 다루기

대규모 문서 저장소에서는 번역 문제가 크게 드러나지 않고 조용히 실패하는 경우가 많으며, 시간이 지나면서 누적됩니다. 최근에 Co-op Translator가 번역을 처리하는 방식에 근본적인 설계 결정을 내렸습니다.

번역은 이제 단순한 정적 출력물이 아니라 **“버전 관리되는 소프트웨어 자산”**으로 취급됩니다.

번역이 조용히 부담이 될 때

대부분의 프로젝트에서는 번역이 완료되면 누군가 명확하게 문제를 발견할 때까지 유효하다고 간주합니다. 그러나 원본 텍스트가 진화하고 코드 예제가 변경되면서, 번역된 콘텐츠가 유창하게 읽히더라도 구식이 됩니다. 이것은 더 이상 번역 품질 문제라기보다는 유지보수 문제입니다.

핵심 질문을 바꿔야 했습니다:

“이 번역이 올바른가?” (X)
“이 번역이 여전히 현재 소스와 동기화되어 있는가?” (O)

결정: 번역을 버전 관리 자산으로

Co-op Translator 0.16.2부터 번역을 의도적으로 버전 관리되는 자산으로 정의했습니다. 이는 Markdown 파일뿐만 아니라 이미지, 노트북, 그리고 다른 모든 번역된 산출물에도 적용됩니다.

새로운 메커니즘을 발명하는 대신, 우리는 pip, poetry, npm과 같은 소프트웨어 의존성 관리 도구를 참고했습니다. 의존성이 오래되었다고 해서 “잘못된 것”이 아니라 단지 현재 버전과 동기화되지 않은 것입니다. 우리는 이 동일한 논리를 문서에 적용했습니다.

주요 변경사항 및 이점

1. 내장된 마커에서 명시적 상태로

이전에는 번역 메타데이터가 파일 내부의 주석 형태로 존재하여 분산되고 놓치기 쉬웠습니다. 이제는 언어별로 구분된 JSON 상태 파일을 사용해 원본 버전, 번역된 산출물, 동기화 상태를 추적합니다. 번역 상태가 이제 리포지터리에서 첫 번째 등급의, 검사 가능한 부분이 되었습니다.

2. 이미지 및 노트북으로 확장

같은 모델이 비텍스트 자산에도 적용됩니다. 원본 이미지가 변경되면 번역된 버전은 즉시 “동기화 불일치”로 표시됩니다. 이는 저장소 내 모든 콘텐츠 유형에서 일관성을 보장합니다.

3. 관찰 가능한 유지보수

이 설계는 다음을 가능하게 합니다:

명시적 편차 탐지: 어느 파일이 오래되었는지 추측하지 않아도 됩니다.
일관된 신호: 텍스트, 이미지, 노트북 모두 동일한 동기화 규칙을 따릅니다.
확장성: 유지보수가 반응형 작업에서 관찰 가능하고 관리 가능한 워크플로우로 전환됩니다.

결론

번역을 소프트웨어 자산으로 모델링함으로써 모호함이 사라집니다. 상태가 보이며 유지보수가 관리 가능해집니다. 질문은 더 이상 번역 편차가 존재하는지 여부가 아니라 “그것을 볼 수 있는가?” 입니다.

참고자료: