다국어 레슨 모음을 관리하고 번역을 영어 원본에 맞춰 유지하기

## 앱 코드는 건드리지 않고 레슨, 글, 번역만 고치기 이 저장소는 콘텐츠 전용 저장소로, 교육용 레슨, 아티클, 그리고 그 번역본을 관리한다. 이 콘텐츠를 렌더링하는 게시용 애플리케이션은 별도의 위치에 있으며 이 저장소의 일부가 아니다. 여기서 다루는 작업은 산문, 구조, 메타데이터이며 애플리케이션 코드가 아니다. 지켜야 할 범위 경계: - 애플리케이션 소스 코드, 빌드 도구, 런타임 설정을 여기에 추가하지 않는다. 사이트의 동작을 다르게 만들어야 하는 변경이 필요하다면, 그 사실을 명확히 밝히고 여기서 즉흥적으로 처리하는 대신 게시용 애플리케이션 쪽에서 필요한 동반 변경을 설명한다. - 콘텐츠 자체에 대해 보고하는 소규모 유지보수 스크립트(예: 번역 상태 보고서)는 정당한 것이며, 편집 전에 대체하기보다 먼저 사용해야 한다. - 모든 파일을 이후 사람인 번역가가 따라야 할 것으로 취급한다. 나에게는 편리하지만 번역 워크플로를 망가뜨리는 변경은 나쁜 변경이다. - 요청이 원본 언어를 대상으로 하는지 번역본을 대상으로 하는지 모호할 때는 작성하기 전에 반드시 확인한다. 잘못 추측하면 뒤에서 설명하는 오래됨(staleness) 추적이 조용히 손상된다. ## 언어별 폴더 구성을 맞추고 영어 원본부터 고치기 이 라이브러리는 예측 가능하고 미러링된 레이아웃을 사용한다. 레슨 파일은 레슨 디렉터리 아래, 그다음 ISO 언어 코드로 명명된 폴더, 그다음 카테고리 폴더, 그리고 마지막으로 문서 자체 순으로 위치한다. 블로그 게시물은 단일 게시물 디렉터리에 위치하며, 날짜 접두사 뒤에 하이픈으로 구분된 슬러그가 붙는 방식으로 이름이 지정되어, 파일명만으로도 시간순 정렬이 눈에 보이도록 한다. 각 언어 아래의 카테고리 집합은 고정되어 있으며 모든 언어에서 동일하다. 공통 카테고리는 기초, 중급, 고급, 스토리지, 테스트, 데이터 처리, 프레임워크별 자료, 그리고 기타 항목이다. 한 언어에만 카테고리를 새로 만들지 않는다. 모든 언어에 추가하거나 아예 추가하지 않는다. 한 언어(보통 영어)가 유일한 원본 기준(source of truth)이다. 다른 모든 언어 디렉터리는 그것의 번역본을 담는다. 여기서 도출되는 규칙: - 실질적인 변경은 먼저 원본 언어에서 이루어진 다음 번역본으로 전파된다. 번역본에만 새로운 사실, 예시, 섹션을 도입하지 않는다. - 번역본은 번역 품질상의 이유(오역, 문법, 오탈자, 로케일 관례)로만 단독으로 수정될 수 있다. - 번역본에서 발견한 오류가 원본에도 존재한다면, 원본을 먼저 수정하고 번역본은 후속 작업으로 처리한다. ## 바뀐 정도에 따라 버전 번호를 올리고 번역에 옮겨 적기 모든 문서는 구분선으로 끝나는 구조화된 메타데이터 블록으로 시작한다. 이 블록은 최소한 버전 문자열, 제목, 그리고 문서를 한두 문장으로 요약하는 짧은 발췌문을 담는다. 아티클 형식의 게시물은 여기에 더해 작성자명, 작성자 링크, 태그, 게시 날짜를 담는다. 버전 필드는 장식이 아니라 기계가 읽는 값이다. 번역본은 번역 대상이 된 원본 문서의 정확한 버전을 그대로 복사한다. 이후 도구가 각 번역본의 버전을 현재 원본 버전과 비교하여 그 번역본이 최신인지, 약간 오래됐는지, 심각하게 오래됐는지를 판정한다. 변경 규모에 따라 원본 버전을 올린다: - 메이저(Major): 문서가 대폭 재작성된 경우. 번역가는 작업을 다시 해야 한다. - 마이너(Minor): 문장, 단락, 예시가 추가되거나 삭제된 경우. 번역가는 검토 후 패치해야 한다. - 패치(Patch): 철자 및 오탈자 수정만 있는 경우. 번역본은 그대로 사용 가능하다. 해당하는 변경 없이 버전을 올리지 않으며, 버전을 올리지 않고 실질적인 변경을 하지도 않는다. 두 오류 모두 오래됨 보고의 정확성을 훼손하는데, 이는 번역된 라이브러리를 정직하게 유지하는 유일한 메커니즘이다. 번역본을 편집할 때는 실제로 더 새로운 원본 콘텐츠에 맞춰 내용을 반영했을 때만 그 버전을 갱신한다. ## '우리' 말투로, 설명보다 예시를 먼저 보이기 로케일 가이드가 이를 재정의하지 않는 한, 모든 콘텐츠에 다음 관례를 적용한다. - 포용적인 1인칭 복수형을 사용한다. 독자는 강의를 듣는 학생이 아니라 함께 작업하는 협력자다. "~해야 한다" 식의 표현보다 "우리"가 자연스럽게 읽히는 곳에서는 그것을 사용한다. - 먼저 보여주고, 그다음 설명한다. 실제로 작동하는 예시가 설명보다 앞선다. 독자는 그것에 대해 읽기 전에 그것을 먼저 본다. - 단락을 짧게 유지한다. 정보가 밀도 높아지면 긴 단락 대신 글머리 기호 목록이나 예시 블록으로 바꾼다. - 능동태를 사용한다. 늘여 쓴 격식체보다 축약형을 일관되게 사용한다. - 이모지는 사용하지 않는다. 상투적인 문구, 축하성 군더더기, 다음 문장을 도입하기 위해서만 존재하는 문장도 넣지 않는다. - 시리얼 콤마(serial comma)를 사용한다. - 제목 레벨: 주요 섹션에는 2단계 제목을, 하위 섹션에는 3단계 제목을 사용한다. 본문 콘텐츠 안에 최상위 제목을 두지 않는다. 그 레벨은 문서 제목 몫이다. - 모든 예시 블록은 렌더러가 올바르게 강조 표시할 수 있도록 언어 식별자를 명시한다. 가르치는 바가 없는 것은 잘라낸다. 길이는 미덕이 아니다. 번역가가 충실하게 옮길 수 있는 짧은 문서가, 흐트러지기 쉬운 긴 문서보다 더 가치 있다. ## 레슨마다 개요, 예시, 관련 주제 순서로 짜기 교육용 문서는 고정된 서술 구조를 따른다: 1. 문서가 다루는 내용에 대한 간단한 개요. 2. 동기 — 왜 이것이 중요한가 — 를 최대 두세 문장으로. 이 섹션을 늘리려는 유혹을 참는다. 군더더기가 가장 자주 쌓이는 곳이다. 3. 구체적인 예시로 이끌어가는 핵심 콘텐츠, 각 예시 다음에 설명이 이어진다. 4. 바깥으로의 연결: 이 주제가 독자가 이미 본, 혹은 다음에 보게 될 인접 자료와 어떻게 관련되는가. 핵심 콘텐츠 안에서는 사용 가능한 가장 단순한 사례에서 더 복잡한 변형으로 순서를 잡고, 어떤 용어에 의존하기 전에 먼저 그것을 소개한다. 문서가 명확히 구분되는 두 주제를 다룰 만큼 커진다면, 늘어지게 두지 말고 분리한다. 초점이 명확한 두 문서가 번역도 더 잘되고, 오래됨도 서로 독립적으로 진행된다. 메타데이터 블록의 발췌문은 개요만으로 작성할 수 있어야 한다. 한두 문장으로 문서를 요약할 수 없다면, 그 문서는 너무 많은 것을 다루고 있는 것이다. ## 새 레슨이나 언어를 추가하고 사이트에 필요한 등록을 알리기 새 원본 문서: 초기 버전을 포함한 완전한 메타데이터 블록과 함께, 올바른 카테고리 아래 원본 언어 디렉터리에 파일을 생성한다. 그런 다음 새 문서를 표시용으로 등록하기 위해 게시용 애플리케이션 쪽에서 동반 변경이 필요한지 명확히 밝힌다. 자동으로 나타날 것이라고 가정하지 않는다. 새 번역: 원본 파일을 동일한 카테고리 경로와 파일명으로 대상 언어 디렉터리에 복사하고, 본문을 번역하고, 제목이나 발췌문처럼 사람이 읽는 메타데이터 값을 번역한다. 구조적 필드명과 버전 값은 손대지 않는다. 버전은 원본과 정확히 일치해야 한다. 새 언어: 새 언어 코드 아래에 다른 모든 언어와 레이아웃이 미러링되도록 전체 카테고리 디렉터리 집합을 생성하고, 첫 번역 문서를 추가하고, 게시용 애플리케이션에 해당 언어를 등록한다. 존재하지만 등록되지 않은 언어 폴더는 아무도 접근할 수 없는 콘텐츠를 만들어낼 뿐이다. 번역을 작성하기 전에, 해당 언어에 대한 로케일별 스타일 노트가 존재한다면 반드시 읽는다. 로케일 노트는 용어 선택, 기술 용어의 음역, 구두점, 경어 등급을 다루며, 충돌할 경우 일반 하우스 스타일보다 우선한다. 번역을 요청받은 언어에 로케일 노트가 존재하지 않는다면, 관례를 임의로 만들어내지 말고 노트를 새로 만들 것을 제안한다. ## 상태 보고서로 가장 오래된 번역부터 최신으로 만들기 번역 표류(drift)는 다국어 라이브러리의 기본적인 실패 양상이다. 이를 의도적으로 관리한다. 어떤 번역 세션이든, 디렉터리를 손으로 뒤지기보다 먼저 라이브러리에 대해 상태 보고서를 실행하는 것으로 시작한다. 자신이 담당하는 언어와 중요한 심각도 수준으로 필터링한다. 완전히 누락된 문서와 심각하게 오래된 것으로 표시된 문서가 최우선이고, 경미한 표류가 그다음이며, 패치 수준의 표류는 가장 마지막으로 미루거나 아예 다루지 않는다. 작업 규칙: - 문서를 부분적으로만 번역해 놓고 버전을 원본과 일치시킨 채로 두지 않는다. 스스로를 최신이라고 보고하는 미완성 번역은, 명백히 누락된 상태보다 더 나쁘다. - 도중에 멈춰야 한다면, 보고서가 계속 그 파일을 표시하도록 버전을 이전 값 그대로 둔다. - 로케일 노트에 비추어 검토하지 않고 기계 번역을 그대로 내보내지 않는다. - 작업을 시작한 이후 원본이 변경되었다면, 마치기 전에 diff를 다시 확인한다. 실제로 기록하게 될 버전을 기준으로 마무리한다. - 마지막에 어떤 문서를 최신으로 만들었는지, 어떤 것을 의도적으로 건너뛰었는지, 그 이유는 무엇인지 보고한다. 다음 기여자는 그것을 바탕으로 우선순위를 정한다.