docs: make English the canonical documentation language - #43
Merged
Conversation
AI-facing development context (commit messages, PR text, release notes, internal working docs) is now English only, and every bilingual document pair flips: NAME.md is the English canonical file, NAME.ko.md the Korean pair. - rename 34 pairs (NAME.md -> NAME.ko.md, NAME.en.md -> NAME.md) and rewrite all intra-doc links and language headers - CHANGELOG.md becomes English-only (drop the per-release Korean section) - cli-reference generator emits cli-reference.md (en) / .ko.md (ko) - translate CLAUDE.md and restate the policy in README/docs/README
Contributor
There was a problem hiding this comment.
Pull request overview
Updates the repository’s documentation and related tooling to make English the canonical language for agent/developer context while keeping user-facing docs bilingual (English canonical, Korean as .ko.md).
Changes:
- Renames and rewrites bilingual doc pairs to the new
NAME.md(English) /NAME.ko.md(Korean) convention with first-line language links. - Makes
CHANGELOG.mdEnglish-only and updatesscripts/release_notes.shcomments/error text accordingly. - Updates the CLI reference drift-gate test to generate
docs/manual/cli-reference.md(English) andcli-reference.ko.md(Korean).
Reviewed changes
Copilot reviewed 40 out of 109 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| tools/gen_verification_set.sh | Updates checklist path; header comments may need English per new code-comment language policy. |
| TODO.ko.md | Adds Korean TODO file (potential conflict with “internal docs are English-only” policy). |
| TODO.en.md | Removed old English TODO filename (deleted). |
| scripts/release_notes.sh | Translates script header/comments and error to English. |
| oracle/README.md | Switches to English-canonical README and updates language links. |
| oracle/README.ko.md | Adds Korean pair for oracle README. |
| oracle/README.en.md | Removes old .en.md variant (deleted). |
| fixtures/README.md | Switches to English-canonical README and updates language links. |
| fixtures/README.ko.md | Adds Korean pair for fixtures README. |
| fixtures/README.en.md | Removes old .en.md variant (deleted). |
| fixtures/golden/README.md | Switches to English-canonical golden README and updates language links. |
| fixtures/golden/README.ko.md | Adds Korean pair for golden README. |
| fixtures/golden/README.en.md | Removes old .en.md variant (deleted). |
| examples/template-spec-v1/README.md | Switches to English-canonical example README and updates language links. |
| examples/template-spec-v1/README.ko.md | Adds Korean pair for the example README. |
| examples/template-spec-v1/README.en.md | Removes old .en.md variant (deleted). |
| examples/part-composition-v1/README.md | Switches to English-canonical example README and updates links (incl. contract link). |
| examples/part-composition-v1/README.ko.md | Adds Korean pair for the example README (updates contract link to .ko.md). |
| examples/part-composition-v1/README.en.md | Removes old .en.md variant (deleted). |
| examples/document-spec-v2/README.md | Switches to English-canonical example README and updates language links. |
| examples/document-spec-v2/README.ko.md | Adds Korean pair for the example README. |
| examples/document-spec-v2/README.en.md | Removes old .en.md variant (deleted). |
| examples/document-spec-v1/README.md | Switches to English-canonical example README and updates language links. |
| examples/document-spec-v1/README.ko.md | Adds Korean pair for the example README. |
| examples/document-spec-v1/README.en.md | Removes old .en.md variant (deleted). |
| examples/certification-v1/README.md | Switches to English-canonical example README and updates language links. |
| examples/certification-v1/README.ko.md | Adds Korean pair for the example README. |
| examples/certification-v1/README.en.md | Removes old .en.md variant (deleted). |
| docs/release-readiness.md | Switches to English-canonical checklist and updates language links/content language. |
| docs/release-readiness.ko.md | Adds Korean pair for release readiness checklist. |
| docs/release-readiness.en.md | Removes old .en.md variant (deleted). |
| docs/README.md | Switches to English-canonical docs index and updates bilingual-doc policy text. |
| docs/README.ko.md | Adds Korean pair for docs index and updates links to .ko.md counterparts. |
| docs/README.en.md | Removes old .en.md variant (deleted). |
| docs/design/18-html-fragment-contract.ko.md | Adds Korean pair for design doc 18. |
| docs/design/18-html-fragment-contract.en.md | Removes old .en.md variant (deleted). |
| docs/design/17-structured-corpus-v1.md | Switches to English-canonical design doc 17 and updates language links. |
| docs/design/17-structured-corpus-v1.ko.md | Adds Korean pair for design doc 17. |
| docs/design/17-structured-corpus-v1.en.md | Removes old .en.md variant (deleted). |
| docs/design/16-certification-v1.md | Switches content toward English (canonical) and updates language links. |
| docs/design/16-certification-v1.ko.md | Adds Korean pair for design doc 16. |
| docs/design/16-certification-v1.en.md | Removes old .en.md variant (deleted). |
| docs/design/15-document-spec-v2.md | Switches content toward English (canonical) and updates language links. |
| docs/design/15-document-spec-v2.ko.md | Adds Korean pair for design doc 15. |
| docs/design/15-document-spec-v2.en.md | Removes old .en.md variant (deleted). |
| docs/design/14-template-spec-v1.ko.md | Adds Korean pair for design doc 14. |
| docs/design/14-template-spec-v1.en.md | Removes old .en.md variant (deleted). |
| docs/design/13-document-spec-v1.md | Switches content toward English (canonical) and updates language links. |
| docs/design/13-document-spec-v1.ko.md | Adds Korean pair for design doc 13. |
| docs/design/13-document-spec-v1.en.md | Removes old .en.md variant (deleted). |
| docs/design/09-diagnostic-corpus.md | Switches to English-canonical design doc 09 and updates language links. |
| docs/design/09-diagnostic-corpus.ko.md | Adds Korean pair for design doc 09. |
| docs/design/09-diagnostic-corpus.en.md | Removes old .en.md variant (deleted). |
| docs/design/08-external-research.en.md | Removes old .en.md variant (deleted). |
| docs/design/00-overview.ko.md | Adds Korean pair for design doc 00. |
| docs/design/00-overview.en.md | Removes old .en.md variant (deleted). |
| crates/hwp-cli/tests/cli_reference.rs | Updates generated doc filenames/links to .ko.md + English-canonical cli-reference.md. |
| crates/hwp-cli/src/cli.rs | Updates doc-gen comment to reflect English-canonical CLI reference naming. |
| corpus/structured-v1/TRACKED_FILES.txt | Updates tracked README filename to .ko.md. |
| corpus/structured-v1/README.md | Switches to English-canonical corpus README and updates language links/content language. |
| corpus/structured-v1/README.ko.md | Adds Korean pair for corpus README. |
| corpus/structured-v1/README.en.md | Removes old .en.md variant (deleted). |
| CLAUDE.md | Translates and updates repo-wide language policy and contributor guidance. |
| CHANGELOG.md | Drops bilingual sections; keeps English-only release notes. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
2
to
6
| @@ -5,7 +5,7 @@ | |||
| # B(책갈피/하이퍼링크)·C(글자효과·요약정보, JSON IR 경유). 각 파일은 우리 리더로 | |||
| # 자체 재검증(재읽기 무경고 + C는 효과 보존 단언)한 뒤에만 통과 표시된다 — 깨진 | |||
Comment on lines
1
to
6
| //! `hwp` CLI 정의 — clap derive 기반 명령/플래그 선언. | ||
| //! | ||
| //! 이 모듈은 lib 타깃으로 노출된다(`hwp_cli::cli`). bin(`main.rs`)이 파싱·디스패치에 | ||
| //! 쓰고, `tests/cli_reference.rs`가 `clap::CommandFactory`로 명령 트리를 introspect해 | ||
| //! `docs/manual/cli-reference.md`(한국어)와 `cli-reference.en.md`(영문)를 자동 생성한다 | ||
| //! `docs/manual/cli-reference.md`(영문 정본)와 `cli-reference.ko.md`(한국어)를 자동 생성한다 | ||
| //! (코드-문서 동기화 게이트). |
Comment on lines
+1
to
+5
| [한국어](TODO.ko.md) · [English](TODO.md) | ||
|
|
||
| # TODO — 스펙 재문서화 & hwp-cli 전면 재검토 | ||
|
|
||
| > **배경:** 실기 검증(C/D 시리즈)에서 발견된 오류들의 분포가 스펙 커버리지 공백과 일치했다 — |
This was referenced Aug 1, 2026
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
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.
Development context that AI agents read is English only from now on: commit messages, PR titles/bodies, release notes, and internal working docs. User-facing docs stay bilingual, but the canonical side flips to English.
NAME.md->NAME.ko.md,NAME.en.md->NAME.md; all links and first-line language headers rewritten accordinglyCHANGELOG.mdis English-only (per-release Korean sections dropped;scripts/release_notes.shis unchanged in behavior)tests/cli_reference.rsnow generatesdocs/manual/cli-reference.md(English) andcli-reference.ko.mdCLAUDE.mdtranslated to English with the new language policy; README/docs README policy paragraphs updatedcorpus/structured-v1/TRACKED_FILES.txtandtools/gen_verification_set.shfollow the renamesscripts/check.shpasses locally.