docs(site): English at /, Korean at /ko/ - #27
Merged
Conversation
The landing page was Korean only, while README.md is English with a
README.ko.md translation and every file under docs/ has a .ko.md twin.
The page was the gap — and it is the one surface a non-Korean reader
arriving from npm cannot fall back from.
Two complete files rather than runtime i18n. The org's hub site keys its
text into an inline dictionary with a language dropdown, and that was the
obvious precedent to copy; it was rejected because THIS repo already has
a documentation convention, used by the README and everything in docs/.
A second mechanism for one page means contributors have to know which
pattern applies where. The duplication is real and accepted: this page
was edited on three releases in two days, and each edit must now be made
twice — the same cost the README already pays, under the same rule that
bilingual pairs move together.
The translation was generated by substitution rather than retyped, and
the script asserts no Hangul survives in the English page. It reported
zero, which is what makes "nothing was skipped" a check rather than a
claim. The only Korean left is the switcher label.
Also fixed while here:
- scripts/build-pages.mjs substituted __PACKAGE_VERSION__ in the root
index.html ONLY. A page in a subdirectory would have shipped the
literal placeholder to readers. It now walks every .html under site/,
logs how many it stamped, and fails if it finds none.
- the block-reasons list was missing blocked_response_size, added in
0.6.0. Fixed in both languages.
- README.ko.md's docs link now points at /ko/.
Verified by serving the built output: both pages 200, cross-links
resolve, both stamped v0.7.0 with no placeholder left, English page
reports lang="en" with all seven section headings in English, Korean page
reports lang="ko" with its content intact. Geometry was not measurable —
the browser pane would not composite — so this is a DOM-level check, not
a visual one; the two pages are byte-identical in structure and styling
by construction.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
로드맵 P2의 마지막 남은 항목. 버전 범프 없음 — 릴리스 안 나갑니다. 사이트는
main머지 시pages.yml이 배포합니다.왜
랜딩 페이지만 한국어 전용이었습니다.
README.md는 영어에README.ko.md번역이 붙고docs/의 모든 파일에.ko.md짝이 있는데 여기만 거꾸로였고, npm에서 들어온 비한국어 독자가 되돌아갈 데가 없는 유일한 표면입니다.왜 런타임 i18n이 아니라 두 파일인가
org 허브 사이트는 인라인 사전 + 언어 드롭다운을 씁니다. 명백한 선례였지만 안 따랐습니다 — 이 repo에는 이미 문서 규약이 있고(짝 파일), README와
docs/전부가 그걸 씁니다. 한 페이지만 다른 메커니즘이면 기여자가 "어디엔 어떤 패턴"인지를 알아야 합니다. 산문·표·코드가 뒤섞인 700줄을 사전으로 개조하는 것도 독자 이득 없이 조용히 깨지기 쉬운 큰 편집입니다.중복은 실재하고 감수합니다. 이 페이지는 이틀 동안 릴리스 세 번에 걸쳐 편집됐고, 이제 두 번씩 해야 합니다. README가 이미 치르는 비용이고 같은 규율(짝은 같은 변경 안에서 함께)로 덮습니다.
번역을 어떻게 검증했나
손으로 옮겨 적지 않고 치환 스크립트로 생성한 뒤, 영어 페이지에 한글이 하나도 안 남았는지 단언했습니다.
"빠뜨린 데 없음"이 주장이 아니라 검사 결과입니다. 남은 한글은 전환 링크 라벨(
한국어) 하나뿐입니다.하는 김에 고친 것
scripts/build-pages.mjs가 루트index.html에만 버전을 치환하고 있었습니다. 하위 디렉터리 페이지였다면v__PACKAGE_VERSION__이 독자에게 그대로 나갔을 겁니다. 이제site/아래 모든.html을 훑고, 몇 개를 스탬프했는지 로그로 남기고, 하나도 못 찾으면 실패합니다.차단 이유 목록에
blocked_response_size가 빠져 있었습니다 — 0.6.0에서 추가됐는데 사이트만 낡아 있었습니다. 양쪽 다 넣었습니다.README.ko.md의 문서 링크는/ko/로 바꿨습니다.검증
빌드 산출물을 실제로 서빙해서 확인:
/·/ko/href="ko/"·href="../"동작v0.7.0, 플레이스홀더 0건lang="en", h2 7개 전부 영어lang="ko", 내용 보존pnpm verify그린(219 테스트/15파일).한계: 브라우저 패널이 또 렌더를 안 잡아서 기하는 측정하지 못했습니다. DOM 레벨 검증입니다. 두 페이지는 구조와 스타일이 구성상 동일하고(텍스트 노드만 치환), 레이아웃에 영향을 주는 변경은 없습니다.
트레이드오프
한국어 페이지가
/→/ko/로 옮겨져 기존 루트 링크는 이제 영어로 착지합니다. 의도한 교정이지만 살아있는 URL이 바뀌는 건 사실입니다. JS-017에 적었습니다.결정 번호는 JS-017을 썼습니다 — CI 세션 몫으로 비워뒀던 번호인데, 그 세션의 PR(#24·#26)이 결정을 추가하지 않고 끝나서 영구 공백을 남기지 않으려고 채웠습니다.