어떤 일이 있었나

블로그 콘텐츠에 대해 일상적인 일괄 업데이트 작업을 수행하고 있었습니다. 작업 내용은 간단했습니다. 기존의 29개 포스트에 커버 이미지 메타데이터를 추가하는 것이었죠. 파일을 순회하며 필요한 프론트매터(front matter)를 삽입하고 변경 사항을 커밋하는 간단한 스크립트를 작성했습니다.

스크립트를 실행하고 diff를 확인해보니 완벽해 보였습니다. 저는 자신 있게 “feat: 모든 포스트에 커버 이미지 추가"라는 메시지와 함께 커밋을 완료했습니다.

하지만 변경 사항을 푸시하고 실제 사이트를 확인했을 때 무언가 잘못되었다는 것을 깨달았습니다. 영어 포스트에는 멋진 새 커버가 적용되어 있었지만, 한국어 버전은 여전히 비어 있었습니다. 콘텐츠의 절반을 완전히 놓쳐버린 것입니다.

근본 원인

근본 원인은 너무 좁게 설정된 스크립트 경로 패턴과 저장소의 다국어 구조를 충분히 고려하지 못한 제 사고방식이었습니다.

제 스크립트는 다음과 같이 너무 구체적인 글로브(glob) 패턴을 사용하고 있었습니다. content/posts/en/**/*.md

“포스트"를 하나의 단위로만 생각하다 보니, 무의식적으로 영어 디렉토리를 먼저 타겟팅했습니다. “일단 여기서 잘 되는지 확인하고 넘어가자"는 생각이었죠. 하지만 일괄 작업의 흐름 속에서 한국어 번역본이 별도의 디렉토리에 살고 있다는 사실을 깜빡했습니다. content/posts/ko/**/*.md

언어 간의 일관성(parity)을 확인하는 검증 단계가 프로세스에 없었습니다. 영어 파일이 업데이트되었으니 작업이 끝났다고 막연히 가정해버린 것입니다.

해결 방법

즉각적인 해결책은 스크립트를 다시 실행하되, 이번에는 한국어 디렉토리를 타겟으로 설정하고 후속 커밋을 생성하는 것이었습니다.

# 두 번째 실행
python update_covers.py --dir content/posts/ko/
git add content/posts/ko/
git commit -m "docs: 누락된 한국어 커버 이미지 메타데이터 추가"

하지만 진짜 해결책은 이런 일이 다시는 발생하지 않도록 워크플로우를 업데이트하는 것이었습니다.

배운 점

1. 다국어 콘텐츠는 명시적인 일관성 체크가 필요합니다. 한 언어에 대한 작업이 다른 언어에도 자동으로 적용될 것이라고 가정해서는 안 됩니다.
2. 포괄적인 경로 패턴을 사용하세요. 다국어 콘텐츠에 대해 일괄 작업을 수행할 때는 모든 언어 디렉토리를 캡처하는 패턴을 사용해야 합니다: content/posts/{en,ko}/**/*.md.
3. 파일 개수를 검증하세요. ls content/posts/en | wc -l과 ls content/posts/ko | wc -l의 결과가 항상 같아야 한다는 간단한 확인만으로도 많은 실수를 방지할 수 있습니다.
4. 사고방식에 다국어를 포함시키세요. 프로젝트가 다국어를 지원한다면, “모든 파일"은 항상 “모든 언어의 모든 파일"을 의미해야 합니다.

예방 조치

앞으로 이러한 “이중 커밋” 상황을 방지하기 위해 몇 가지 안전장치를 도입했습니다.

• Pre-commit Hook: 커밋 전에 en과 ko 디렉토리 사이의 파일 개수 일치 여부를 확인하는 스크립트를 추가했습니다. 일치하지 않으면 커밋이 차단됩니다.
• CI 검사: CI 파이프라인에 영어 포스트가 추가되거나 업데이트될 때 한국어 디렉토리에 대응하는 변경 사항이 없으면 경고를 띄우는 단계를 추가했습니다.
• 체크리스트 업데이트: 내부 “일괄 작업 체크리스트"에 필수 항목을 추가했습니다: “EN과 KO 디렉토리를 모두 타겟팅했는가?”

다국어 블로그를 운영하는 것은 두 배의 노력이 들지만, 두 배의 실수를 의미해서는 안 됩니다. 일관성 체크를 자동화함으로써, 두 번 커밋하는 번거로움 없이 한국어 독자들에게도 영어 독자들과 동일한 고품질의 경험을 제공할 수 있게 되었습니다.