데이터 파일로 만드는 다국어 자료 목록을 페이지를 직접 고치지 않고 관리하기

## 목록 페이지는 데이터 파일로 만들어진다는 점 알기 당신은 사람이 보는 출력물이 직접 **작성**되는 것이 아니라 **생성**되는 큐레이션 지식 베이스를 관리한다. 무엇이든 손대기 전에 이 구분을 이해해야 한다. - **진실 공급원**은 구조화된 데이터 파일 집합이다. 즉 (앵커와 목차를 정의하는) 카테고리/섹션 트리와, 섹션별 항목 파일 하나씩이다. - **생성 산출물** — 사람이 읽을 수 있는 목록 문서(지원 언어별 하나씩)와 기계가 읽을 수 있는 인덱스 — 는 이 데이터로부터 생성기 스크립트에 의해 만들어진다. 이들은 소모품이며 필요할 때마다 다시 만들어진다. - 동일한 기저 데이터는 자동화된 에이전트를 위한 런타임 쿼리 인터페이스에도 공급될 수 있으므로, 데이터 품질은 렌더링된 문서 이상의 소비자를 갖는다. 여기에는 일반적으로 애플리케이션 런타임도, 빌드도, 테스트 스위트도 없다. 모든 변경 사항은 구조화된 데이터, 도구 스크립트, 문서 중 하나에 해당한다. 이 사고 모델을 유지하라 — 이것이 가장 흔하고 가장 치명적인 실수, 즉 곧 덮어써질 출력물을 수정하는 실수를 막아준다. ## 페이지 대신 데이터를 고치고 다시 만들기 - **생성된 출력 문서를 절대 직접 편집하지 마라.** 수정 내용은 다음 재생성 시 모두 사라진다. 독자가 보는 내용을 바꾸려면 기저 데이터를 바꿔라. - 항목을 추가하거나 수정하려면 해당 섹션의 항목 파일을 편집하라. - 새 섹션을 추가하려면 먼저 카테고리/섹션 트리 파일을 편집한 뒤, 그에 맞는 항목 파일을 생성하라. 그 후 앵커 검증 도구를 실행하여 외부에서 참조하는 앵커가 유실되지 않았는지 확인하라. - 데이터를 변경한 후에는 커밋하기 전에 로컬에서 생성기를 실행하여 모든 생성 파일을 갱신하라. 지속적 통합(CI)은 새로 생성된 출력물과 어긋나는 작업 트리를 거부한다 — 추측하지 말고 재생성하라. - 기계가 읽을 수 있는 인덱스를 직접 편집하지 마라. 이는 생성기에 의해 완전히 재생성된다. ## 항목의 칸을 채우고 독자용 한 문장 설명 쓰기 각 항목은 필수 필드(안정적인 고유 id, URL, 제목, 카테고리, 유형, 난이도, 언어 집합, 추가일, 상태)와 자동화에 의해 채워지는 선택 필드(아카이브 URL, 마지막 확인 타임스탬프, 콘텐츠 지문)를 가진 구조화된 레코드다. 유형·난이도·언어·상태에 대한 통제 어휘(controlled vocabulary)를 준수하라 — 값을 임의로 만들어내지 마라. 항목에 딸린 자유 텍스트 설명은 **외부에 공개되어 제3자가 읽는 문구**로 취급하라. - **포함할 것**: 해당 리소스가 무엇인지 설명하는 사실적인 문장 한 개, 그리고 선택적으로 뒤따르는 저자 서명. - **제외할 것**: 내부적인 모든 것 — 이 프로젝트에 대한 언급, 이슈나 변경 요청 번호, "원래 제안자" 같은 표현, 그 밖의 이력 메타데이터. 저작자 표시는 이미 버전 관리 이력에 보존되어 있다. 외부 독자가 해당 항목과 이 저장소 사이의 어떤 관계도 유추할 수 없어야 한다. - 원본이 잘못되었거나 오래되지 않은 한, 기계로 이전(migrate)된 값은 그대로 두라. - 원저자가 명시적으로 요청한 경우(유료 콘텐츠, 삭제 요청)에만 해당 항목을 외부 아카이빙에서 제외하라. ## 외부 링크가 끊기지 않게 섹션 링크 이름을 바꾸지 않기 외부 사이트와 내부 목차는 모두 명명된 앵커를 가리킨다. 기존 앵커의 이름을 바꾸거나 제거하면 그것을 대상으로 하는 모든 인바운드 링크가 아무 경고 없이 깨진다. - **기존 앵커의 이름을 바꾸거나 제거하지 마라.** 대신 새 섹션에는 새 앵커를 추가하라. - 지속적 통합(CI) 가드는 현재 앵커 집합을 기준선과 비교하여 기준선 앵커가 하나라도 누락되면 빌드를 실패시킨다. 이 가드를 제안이 아니라 반드시 통과해야 하는 관문으로 취급하라. - 생성기는 항목을 결정적으로(추가일, 그다음 제목 순으로) 정렬하므로, 항목을 손으로 일괄 재정렬하지 마라. 목록에서 항목을 앞으로 옮기려면 레코드를 재배치하는 대신 추가일 값을 변경하라. ## 코드와 메모는 한 가지 주 언어로 쓰고 항목마다 실을 언어판 정하기 프로젝트가 직접 작성하는 콘텐츠는 하나의 주 언어로 작성한다. 여러 언어가 등장하는 경우는 다국어 사용이 산출물 자체에 본질적으로 내재된 경우로 한정된다: 번역된 출력 문서, 지역화된 섹션 제목 오버라이드, 리소스의 원본 언어를 그대로 유지하는 항목별 제목, 그리고 주 언어가 아닌 프롬프트에서 작동하도록 만들어진 트리거 문구가 그 예다. 그 외 모든 것 — 코드, 주석, 필드명, 템플릿, 파이프라인 출력, 라벨, 커밋 메시지 — 은 주 언어로 유지한다. 하나의 항목은 언어 집합에 의해 제어되어 여러 언어판에 나타날 수 있다. - 언어 힌트가 없는 새 항목 → 주 언어판에만 등재하고, 기여자에게 다른 언어판에도 넣고 싶은지 물어보라. - 특정 로케일 전용 리소스 → 해당 로케일로만 태그하라. - 진정으로 문화를 초월한 표준 리소스 → 관련 언어 전체에 태그하거나, 와일드카드를 신중하게 사용하라. - 구조를 맞추기 위한 목적만으로 항목을 여러 언어판에 강제로 번역하거나 강제로 복제하지 마라. 각 언어판은 다른 언어판에는 없는 항목을 포함할 수 있다. ## 기여를 받아들일 때 기여한 사람의 이름 표시 지키기 인바운드 요청은 두 가지 형태로 들어오며, 공로가 절대 유실되지 않도록 이식(port)해야 한다. - **구조화된 제안(브랜치 없음):** 항목을 데이터 모델에 직접 이식하고, 재생성하고, 검증기를 실행한 뒤, 제출자에게 공로를 표시하는 공동저자(co-author) 트레일러와 함께 커밋하라 — 이 트레일러가 그들의 유일한 공로 표시다. - **직접 변경 요청(기여자가 자신의 브랜치에서 파일을 편집한 경우):** 작업을 *기여자의 브랜치에서* 이식하여, 그 변경 사항이 저작자 표시를 온전히 유지한 채 병합되도록 하라. 기여자의 직접 변경 사항을 자체적으로 경쟁 요청을 열고 기여자의 요청을 닫아버리는 자동화 어시스턴트를 통해 처리하지 마라 — 그러면 기여자의 병합 공로가 사라진다. 자동화된 코딩 어시스턴트는 관리자가 자리를 비웠고 대기열을 계속 진행시켜야 할 때, **구조화된 제안에 한해서만 비동기 폴백**으로 사용할 수 있다. 이는 기본 경로가 아니며, 병합 전에 여전히 사람이 결과를 검토한다. 어시스턴트는 타이핑을 대신할 뿐 판단을 대신하지 않는다. ## 모든 변경을 자동으로 확인하고 리뷰 봇은 조언만 하게 하기 데이터나 생성기 스크립트를 건드리는 모든 변경에 대해, 파이프라인은 다음을 수행해야 한다. 1. 스키마 검증과 앵커 검증을 실행한다. 2. 생성기를 다시 실행하여, 작업 트리가 새로 생성된 출력물과 어긋날 경우 경고한다(기여자가 재생성을 잊었다는 신호다). 3. 공개된 채점 기준(rubric)에 따라 새 항목마다 점수를 매기고, 구조화된 댓글 하나를 게시하며, 권고성 라벨을 적용하는 자동 리뷰 봇을 호출한다. 리뷰 봇은 보수적으로 설계하라. 기여자의 언어는 (모델을 통해서가 아니라) 결정적인 방식으로 감지하여 지시문으로 전달하고, 모델 호출이 실패하면 별도의 "review-failed" 라벨 아래 결정적인 도달 가능성 검사와 형식 검사로 폴백하라. **이 봇은 절대 자동 병합하지 않으며 절대 자동 거부하지도 않는다** — 조언만 할 뿐 판단은 사람이 한다. ## 페이지를 직접 고치지 않고, 규칙에 없는 변경은 멈추고 묻기 다음을 하지 마라: - 생성된 출력 문서나 기계가 읽을 수 있는 인덱스를 손으로 편집하는 것. - 기존 앵커의 이름을 바꾸거나 제거하는 것. - 템플릿에서 프로젝트가 허용하는 태그 화이트리스트를 벗어난 마크업을 도입하는 것. - 정렬 키를 조정하는 대신 기존 항목을 일괄 재정렬하는 것. - 명시적으로 요청받지 않는 한 기여 가이드라인, 행동 강령, 워크플로 정의를 편집하는 것. - 명시적으로 요청받지 않는 한 커밋을 생성하거나 푸시하는 것. 변경 사항이 이 규칙들이 다루지 않는 영역으로 넘어갈 때 — 새 언어판, 새 스키마 필드, 새 섹션 분류 체계 등 — 즉흥적으로 처리하지 말고 멈춰서 물어보라. 기여 가이드와 채점 기준의 취지를 따르고, 확신이 서지 않을 때는 행동하기 전에 사람에게 확인하라.