- [Python/Static Web] JSON 사전 7개와 Python 237줄로 50개 다국어 웹페이지를 한 번에 만들고 검증하는 구조2026년 11월 16일 20시 33분 28초에 업로드 된 글입니다.작성자: kugorang
TL;DR
- 2026-11-15
kugorang/kugorang.github.ioPR #2(83c5a06)에서 개인 포트폴리오를 쿠고랑 (kugorang) 5대 제품 공식 사이트(hw.kugora.ng)로 바꾸며 49개 파일을 한 번에 갱신했습니다. - Python 표준 라이브러리만 쓰는
scripts/build.py(237줄)가 7개 언어(ko,en,ja,de,fr,es,pt-BR) 번역 파일(언어당 132개 문장)과 제품 목록을 읽어 HTML·XML·텍스트 파일 50개(합계 377,654바이트)를 만듭니다. - 실행 전
translations()와catalog()가 누락된 키·잘못된 자리표시자·미출시 앱의 스토어 링크를 즉시 차단하고,build.py --check(중앙값 123.6ms)와tests/test_site.py(9개 검사 0.141초 통과)로 결과를 검증합니다.
1. 문제: 7개 언어 페이지 50개를 손으로 고치면 반드시 어긋난다
쿠고랑 (kugorang)은 앱 2종(필데이, CakeTogether)과 게임 3종(Facet, 달빛 고물상, 오선로)을 공식 사이트
https://hw.kugora.ng에서 소개합니다. 이 사이트는 7개 언어(ko,en,ja,de,fr,es,pt-BR)를 지원합니다.정적 웹사이트는 서버에서 매번 화면을 계산하지 않고, 미리 만들어 둔 HTML 파일을 그대로 내려보내는 방식입니다. 7개 언어마다 첫 화면(
/index.html), 앱 목록(/apps/), 게임 목록(/games/), 기획 소개(/apps/caketogether/), 오류 페이지(/404.html), 리다이렉트(/Facet/index.html)를 따로 두면 생성 파일이 총 50개가 됩니다.2026-11-15 커밋
83c5a06(PR #2)에서는 사이트 제목, 소개 문장, 문의 이메일 주소(hw@kugora.ng)를 개인 기준에서 사업체 쿠고랑 (kugorang) 기준으로 바꿨습니다. 이때 바뀐 파일이 49개입니다.만약 사람이 HTML 파일 49개를 일일이 열어 문장을 고치면 다음 세 가지 사고가 납니다.
- 한 언어의 HTML 파일만 고치고 다른 언어 파일을 빠뜨립니다.
- 아직 출시하지 않은 개발 중 게임 카드에 잘못된 앱스토어 설치 버튼이 들어갑니다.
- 검색엔진이 읽는
sitemap.xml목록과 실제 HTML 파일 주소가 달라집니다.
그래서 수정은 원본 데이터 파일(
data/)만 고치고, 나머지 50개 파일은 프로그램이 전부 다시 생성하도록 만들었습니다.
2. 전체 흐름: 데이터 입력 → 규칙 검사 → 50개 파일 생성 → 자동 검증
이 저장소에서 웹사이트가 만들어지고 검사되는 순서는 네 단계입니다.

먼저 2026-11-15 기준 실제 저장소를 내려받아 측정한 파일 구성입니다.
구분 파일 또는 경로 실측 크기 또는 개수 역할 언어 목록 data/languages.json7개 언어 (262바이트) 지원하는 언어 코드와 표시 이름 번역 사전 data/locales/*.json7개 파일 (한국어 ko.json9,127바이트, 132개 항목)화면 제목·설명·버튼 문구 제품 목록 data/projects.json5개 제품 (81줄) 상태, 플랫폼, 기술 스택, 상세 주소 생성기 scripts/build.py237줄 (19,805바이트) 데이터 검증 및 50개 파일 생성 검증 테스트 tests/test_site.py147줄, 9개 테스트 HTML 구조·접근성·XML 검사 최종 출력 생성 파일 전체 50개 파일 (377,654바이트) 다국어 HTML, sitemap.xml,robots.txtscripts/build.py는 외부 패키지를 하나도 설치하지 않고 Python 3 기본 모듈(argparse,html,json,pathlib,re,string,urllib.parse)만 사용합니다. 어떤 컴퓨터나 자동화 서버에서도pip install없이 바로 실행할 수 있습니다.
3. 생성기 내부 동작:
build.py가 실수를 막는 다섯 가지 방법3.1 번역 파일 7개의 키와 자리표시자가 100% 같은지 먼저 확인한다
JSON은 이름(키)과 값(내용)을 짝지어 저장하는 문서 형식입니다.
"count.all": "총 {count}개"에서 중괄호로 감싼{count}안에 숫자를 나중에 끼워 넣는 부분을 자리표시자(placeholder)라고 부릅니다. 만약 영어 파일에{count}를 빠뜨리거나 이름을{cnt}로 잘못 적으면, 실행 중에 화면이 깨지거나 오류가 납니다.translations()함수는 한국어 파일(ko.json)을 기준으로 삼아 나머지 6개 언어 파일이 같은 키 132개와 같은 자리표시자를 가졌는지 빌드를 시작하자마자 비교합니다.def translations(): result = {code: json.loads((ROOT / f'data/locales/{code}.json').read_text()) for code in CODES} base = result['ko'] fields = lambda value: {name for _, name, _, _ in Formatter().parse(value) if name} for code, messages in result.items(): if set(messages) != set(base): raise ValueError(f'{code}: translation keys differ: {set(messages) ^ set(base)}') for key, value in messages.items(): if not isinstance(value, str) or not value.strip() or fields(value) != fields(base[key]): raise ValueError(f'{code}: missing text or mismatched placeholders: {key}') return resultFormatter().parse(value)는 Python 표준 라이브러리가 문자열 안에서{이름}형태만 골라내 주는 기능입니다. 빈 문자열(not value.strip())도 허용하지 않습니다. 번역이 한 줄이라도 비어 있으면 HTML을 만들기 전에 즉시 멈추고 어느 언어, 어느 키가 문제인지 바로 알려 줍니다.3.2 미출시 프로젝트에 스토어 설치 링크가 붙는 것을 코드로 막는다
제품 정보는
data/projects.json에 적습니다. 각 제품에는status값이released(출시됨),development(개발 중),concept(기획 중) 중 하나로 들어갑니다.stores = item.get('stores', {}) if stores and item['status'] != 'released': raise ValueError(f'Unreleased project cannot have install links: {item["id"]}') for store, address in stores.items(): parsed = urlparse(address) expected_host = {'App Store': 'apps.apple.com', 'Google Play': 'play.google.com'}.get(store) if parsed.scheme != 'https' or not expected_host or parsed.netloc != expected_host: raise ValueError(f'Invalid store URL: {item["id"]}')catalog()함수는 두 가지 규칙을 강제합니다.status가'released'가 아닌데stores항목(App Store, Google Play 주소)이 있으면ValueError를 내고 중단합니다. 현재 5대 제품 중fillday만'released'이고,facet,moonjunk,oseonro는'development',caketogether는'concept'입니다.- 스토어 주소는 반드시
https://로 시작해야 하고, 도메인도apps.apple.com또는play.google.com이어야 통과합니다.
사람이 "개발 중인 게임에 실수로 다운로드 링크를 넣지 말자"고 머리로 기억하는 대신, 프로그램이 저장 데이터 자체를 검사해 불가능하게 만든 구조입니다.
3.3 50개 파일의 정확한 계산식과
sitemap.xml생성output_files()함수는 메모리에 50개 파일의 경로와 내용을 먼저 dictionary(사전) 형태로 모두 조립합니다.- 7개 언어 × 5개 기본 경로(
/,/apps/,/games/,/apps/caketogether/,/404.html) = 35개 - 한국어(
ko)를 루트 기본 경로에도 한 번 더 복사 (default=True) = 5개 - 기존 경로 호환용
/Facet/index.html리다이렉트 (7개 언어 + 루트 기본 1개) = 8개 - 검색엔진 안내 파일
robots.txt+sitemap.xml= 2개 - 합계: 35 + 5 + 8 + 2 = 50개
특히 모든 HTML
<head>안에는 검색엔진이 언어별 페이지를 헷갈리지 않도록 두 가지 태그를 자동으로 넣습니다.rel="canonical": "이 페이지의 대표 주소는https://hw.kugora.ng/ko/apps/입니다"라고 알려 주는 태그.rel="alternate" hreflang="...": "같은 내용의 영어·일본어·독일어·프랑스어·스페인어·포르투갈어 페이지 주소가 여기 있습니다"라고 7개 언어와 기본값(x-default) 총 8개를 서로 연결해 주는 태그.
sitemap.xml은 오류가 나는404.html을 빼고 4개 경로 × 7개 언어 = 28개 URL만 XML 형식으로 씁니다. 각<url>항목 안에는 자기 주소(<loc>) 1개와 언어 연결(<xhtml:link>) 8개, 총 9개의 하위 태그가 들어갑니다.3.4
--check옵션: 파일이 하나라도 낡았으면 빌드 단계를 멈춘다build()함수는--check옵션을 붙이면 디스크에 새 파일을 쓰지 않고, 지금 디스크에 있는 파일 내용과 코드가 방금 계산한 문자열이 한 글자라도 다른지만 비교합니다.def build(check=False, output_dir=ROOT): output = output_files() outdated = [] for name, content in output.items(): path = output_dir / name if check: if not path.exists() or path.read_text() != content: outdated.append(name) else: path.parent.mkdir(parents=True, exist_ok=True) path.write_text(content) if outdated: raise SystemExit('Run python3 scripts/build.py; stale files: ' + ', '.join(outdated)) print(f'{"Verified" if check else "Built"} {len(output)} files / {len(CODES)} languages.')예를 들어 누군가
data/locales/ko.json만 고치고python3 scripts/build.py를 다시 실행하지 않으면,python3 scripts/build.py --check가SystemExit와 함께 낡은 파일 목록을 출력하며 종료 코드 1로 멈춥니다.
4.
tests/test_site.py: HTML 50개를 직접 파싱해서 확인하는 9가지 검사build.py가 에러 없이 끝났더라도 HTML 문법이나 접근성 속성이 틀렸을 수 있습니다.tests/test_site.py는 Python 표준html.parser.HTMLParser로 생성된 HTML 50개를 전부 다시 읽어서 9개 항목을 검사합니다.class Document(HTMLParser): def __init__(self, source): super().__init__(convert_charrefs=True) self.elements = [] self.ids = [] self.feed(source) def handle_starttag(self, tag, attrs): attrs = dict(attrs) self.elements.append((tag, attrs)) if 'id' in attrs: self.ids.append(attrs['id'])9개 테스트가 실제로 확인하는 항목입니다.
- 지원 언어 일치:
CODES목록이 정확히 7개인지 확인합니다. - 데이터 일관성:
projects.json의 한글 제목·설명과ko.json의 같은 항목 문장이 똑같은지 대조합니다. - 누락 키 차단: 없는 키(
absent.key)를 부르면 기본값으로 넘어가지 않고 반드시KeyError를 내는지 확인합니다. - HTML SEO 및 접근성 전수 검사: 7개 언어 × 5개 페이지(35개)에서
lang속성,canonical주소,hreflang8개가 모두 실제 생성 파일에 존재하는지, 페이지 내id값이 중복되지 않는지,aria-controls·aria-describedby·aria-labelledby가 가리키는id가 실제로 존재하는지,<img>마다alt설명이 있는지, 영어/유럽어 페이지에 번역 안 된 한글 문장이 섞이지 않았는지 검사합니다. - 출시·개발 상태 분리: 메인 화면 추천 목록에
fillday와facet만 나오는지, 게임 목록에는 스토어 설치 버튼이 없는지 확인합니다. - 미출시 설치 링크 거부 시험: 테스트 안에서
projects.json의status를 임시로'development'로 바꿨을 때ValueError('Unreleased ...')가 실제로 발생하는지 검증합니다. - 기획 단계(
concept) 경계 검사:CakeTogether페이지에<form>태그나 스토어 링크가 없고, 내부 기획 수치가 노출되지 않았는지 확인합니다. - XML 사이트맵 검사:
sitemap.xml이 정확히 28개<url>항목과 각 9개 하위 요소를 갖고/404.html을 포함하지 않는지 확인합니다. - 기존 경로 유지:
Facet/index.html8개 파일이 모두https://facet.kugora.ng/로 연결되는지 확인합니다.
5. 도메인 분리 구조:
hw.kugora.ng와kugora.ng가 부딪히지 않게 두는 법쿠고랑 (kugorang)은 하나의 루트 도메인
kugora.ng아래에서 용도별로 호스트 주소를 나누어 운영합니다.
https://kugora.ng/: 개인 기술 블로그(티스토리)가 연결되어 있습니다. 루트 도메인을 회사 페이지로 덮어쓰면 기존 기술 글 주소(/76,/77등)가 모두 끊어지므로 그대로 유지합니다.https://hw.kugora.ng/: GitHub Pages(kugorang/kugorang.github.io)가 연결된 사업·제품 공식 사이트입니다.https://pokat.kugora.ng/: iMessage 스티커 앱 포캣(kugorang/pokat)의 안내 페이지입니다. 오늘(2026-11-15새벽 커밋7c0f00d) App Store 무료 출시 링크가 반영되었습니다.https://www.kugora.ng/: 티스토리를 가리키는 CNAME 레코드가 있으나 TLS 인증서 이름 점검이 필요한 상태로 분리 관리합니다.
실제로 2026-11-15 19시(KST) 기준 로컬 저장소 테스트와 공개 웹 응답을 측정한 결과입니다.
측정 항목 실행 명령 또는 대상 실측 결과 빌드 일치 확인 python3 scripts/build.py --check(5회)중앙값 123.6ms(최소116.51ms, 최대133.57ms), 50개 파일HTML·XML 단위 검사 python3 tests/test_site.py9 tests OK, 소요0.141s생성 파일 합계 output_files()50개 파일377,654바이트(약 368.8KB)한국어 홈페이지 응답 https://hw.kugora.ng/ko/HTTP 200,11,392바이트,0.478s포캣 안내 페이지 응답 https://pokat.kugora.ng/HTTP 200,23,015바이트,0.668s
6. 엔지니어링 헌법: 코드 수정 ≠ 모의 시험 ≠ 실기기 검증 ≠ 운영 반영
5대 프로덕트(Flutter 기반 Fillday·달빛 고물상·CakeTogether,
Unity 6 (Unity 6.3)기반 Facet·오선로)와 웹 저장소를 다룰 때 쿠고랑 (kugorang)은 네 단계를 엄격히 구분합니다.- 코드 수정:
data/locales/*.json과scripts/build.py를 수정해83c5a06커밋으로 반영한 단계입니다. - 모의 시험:
python3 scripts/build.py --check가 50개 파일 일치(123.6ms)를 확인하고,python3 tests/test_site.py가 9개 HTML/XML 규칙(0.141s)을 통과한 단계입니다. - 실기기 검증: GitHub Pages 배포 후
https://hw.kugora.ng/ko/와https://pokat.kugora.ng/에 실제 HTTP 요청을 보내HTTP 200응답과 본문 바이트를 확인한 단계입니다. 다만 7개 언어 화면 전체를 실제 모바일 기기 Safari·Chrome에서 눈으로 눌러 확인하는 작업은 별개입니다. - 운영 반영: PR #2가
main에 병합되어 공개 웹에 노출된 상태입니다. 단, 하위 도메인(hw.kugora.ng)에 대한 외부 기관의 심사 결과는 아직 확정되지 않은 상태입니다.
7. 트러블슈팅 FAQ
Q1. React나 Next.js 같은 프레임워크 대신 Python 스크립트 237줄로 HTML을 직접 만드는 이유가 무엇인가요?
이 사이트는 회원 로그인이나 실시간 댓글이 없는 5개 제품 소개 페이지입니다. 외부 JavaScript 프레임워크를 쓰면 패키지 수백 개를 설치하고 보안 업데이트를 계속 챙겨야 하지만, Python 표준 라이브러리만 쓰면 237줄 코드로0.12초만에 50개 파일을 만들고0.14초만에 전수 검사를 끝낼 수 있습니다.Q2. Unity 6 (Unity 6.3) 게임이나 Flutter 앱의 상태가 바뀌면 사이트는 어떻게 고치나요?
data/projects.json에서 해당 프로젝트의status값(development→released)과stores주소를 바꾸고, 7개 언어 JSON 파일을 갱신한 뒤python3 scripts/build.py를 한 번만 실행하면 됩니다. 만약 7개 언어 중 하나라도 키가 빠지면translations()가 오류를 내고 멈추기 때문에 불완전한 상태로 배포되지 않습니다.Q3. AI 코딩 도구가 번역 파일이나 HTML을 고칠 때 실수를 막으려면 어떻게 하나요?
OpenAI(ChatGPT, Codex, Dots), Anthropic(Claude Code, Claude), xAI(Grok Bot, Grok), Pickle, Inc.(Pickle) 같은 도구에게 "주의해서 고치라"고 말로만 지시하면 가끔 실수가 납니다. 대신 맞으면 0, 틀리면 1을 내는 자동 검사 프로그램(build.py --check,tests/test_site.py)을 먼저 만들어 두면, 어떤 도구가 코드를 고쳐도 빌드 단계에서 잘못된 부분을 즉시 걸러 낼 수 있습니다.
작성: 쿠고랑 (kugorang) · 2026-11-16
728x90728x90'회고 & 컬럼 > 쿠고랑 개발일지' 카테고리의 다른 글
[Python/AEO] llms.txt와 자동 생성 주제 색인으로 220개 항목 저장소를 AI가 바로 읽는 문서로 바꾸기 (0) 2026.11.14 [쿠고랑 AI 일일 개발일지 #01] Unity 6 UI Toolkit 실측 픽셀 대조: USS cubic-bezier 미지원 결함 해결기 (0) 2026.11.08 다음글이 없습니다.이전글이 없습니다.댓글 - 2026-11-15