[DONE] 한국어·영어 짝 문서가 서로 맞는지 표 하나로 본다

[patternflow-bot]

lsh / https://claude.ai/code/session_01XpnQenA4LEuf6agZAbiq9y

문서 지도 스크립트가 이제 한국어·영어로 같이 두는 글 1,366쌍(일지 37편, 가이드 페이지와 문구, 로드맵, 아틀라스)을 찾아 어느 쪽이 빠졌거나 짧은지 표 하나로 남긴다. 머지하면 두 언어가 어긋난 26곳이 한 장에 보이고, 나중에 생길 *.ko.md 같은 짝도 손대지 않고 같은 표에 들어간다.

좋아지는 것: 없음

할 일

• 계획서 C1 절과 rfc-cleanup §2.3 읽기
• web/scripts/doc-map.ts 에 짝 표 출력 추가 (파일·경로·{ en, ko } 문구·Ko/En 필드)
• npm run doc-map 로 2026-10-doc-parity.csv·2026-10-doc-map.csv 다시 만들기 — 두 번 돌려 바이트 같음
• typecheck·lint 통과, check_links.py 통과
• 짝을 일부러 깬 임시 작업 트리로 빠진 쪽 판정 확인 (.ko.md·콘솔 짝·일지·가이드 경로·Ko 필드)
• 기준 브랜치(dev) merge (이미 최신) 후 [DONE]

정리 PR 세 줄 (rfc-cleanup §2.11)

• What changed: web/scripts/doc-map.ts gains a second output, docs/investigations/2026-10-doc-parity.csv (new, generated); 2026-10-doc-map.csv regenerated by the same command. No source file, no translation.
• §2.1 commands: npm run typecheck, npm run lint (no file under web/src/ or firmware/ changes, so build.sh all, check:ci, check:panels do not apply; web-ci runs check:ci on the PR anyway).
• Doc-map rows: 41 removed / 44 added — the BUILD_GUIDE_v2.md rows now read docs/legacy/BUILD_GUIDE_v2.md (A1, [DONE] 옛 v2 조립 가이드를 docs/legacy/ 로 옮겨 루트에서 한 장 덜어낸다 #13, which discarded its CSV as the plan says), plus two new rows from the step-1 plan's own links. 0 do not resolve.

한 일

doc-map.ts 끝에 「The parity list」 절을 붙였다. 짝을 네 종류로 찾는다:

kind	무엇	지금
file	다른 언어 이름표를 단 쌍둥이 파일: x.ko.md ↔ x.md, 일지 x.en.mdx ↔ x.mdx	37 (일지)
route	web/src/app 의 페이지와 ko/·en/ 쌍둥이 (둘 다 있는지만 — 글은 copy 줄에)	7 (가이드 5, 일지 2)
copy	web/src 에서 en·ko 를 같이 가진 객체, 양쪽을 나란히 걸어 잎마다 한 줄	868
field	Ko/En 쌍둥이 필드: title/titleKo(맨 이름이 영어), nm/nmEn(맨 이름이 한국어)	454 (로드맵 173, 아틀라스 281)

열은 계획서가 제안한 그대로 kind,en,ko,en_chars,ko_chars,state, state 는 ok·missing-en·missing-ko·en-short·ko-short. 글자 수는 마크업을 벗긴 뒤 공백이 아닌 글자다. TypeScript 는 실행하지 않고 컴파일러로 읽기만 한다(.tsx 컴포넌트 안 문구도 그래서 읽힌다).

길이 비교를 글자 수 그대로 하면 표가 쓸모없어진다 — 한국어는 같은 문장을 영어 글자의 0.44배로 쓴다(일지 37쌍, 편차 ±5%). 고정 비율 하나(0.5)만 곱해 돌렸을 때도 402줄(en-short 285, ko-short 117)이 짧다고 나왔고, 대부분 라벨이나 양쪽이 같은 값이었다. 그래서 비교만 이렇게 한다(열의 숫자는 날 글자 수 그대로):

• 한글 음절 하나 = 영어 2.4글자로 잰다 (일지 37쌍 중앙값 2.41, p10 2.28 · p90 2.52). 한국어 문장 속 영어 낱말은 1:1이라 섞인 글도 맞게 잰다.
• 한쪽이 다른 쪽의 2/3 아래면 짧다. 단 긴 쪽이 한 문장(영어 40글자) 아래인 라벨·제목은 비교하지 않고 ok.
• 양쪽이 같은 문장이면 번역이 안 된 것 — 언어가 틀린 쪽을 missing 으로 둔다. 같은 짧은 값(id, 파일 이름, 「Patternflow」 같은 이름, URL·경로)은 번역이 아니라서 줄에서 뺀다(166개).

증거

$ cd web && npm run doc-map
1010 links from 194 files → docs/investigations/2026-10-doc-map.csv
0 do not resolve
1366 Korean/English pairs → docs/investigations/2026-10-doc-parity.csv
7 en-short, 18 ko-short, 1 missing-ko, 1340 ok
$ npm run doc-map  # 두 번째 — cmp 로 두 CSV 모두 바이트 같음
IDENTICAL
$ npx tsc --noEmit -p .          # exit 0
$ npm run lint                   # ✖ 12 problems (0 errors, 12 warnings) — 경고는 모두 이 PR 밖 파일
$ python3 .github/scripts/check_links.py
all 634 relative links resolve

오늘 표가 짚는 26곳 (ok 아닌 줄 전부):

• missing-ko 1 — components/guide/copy.ts#COPY.ko.ui.install.confirm: 한국어 가이드가 기기 콘솔의 「Format pattern storage?」 확인 창 글(console/patterns.html)을 영어 그대로 옮겨 둔 줄이다 (86 = 86). 기기 화면이 영어라 일부러일 수 있다 — 판단은 창작자 몫.
• en-short 7 — 한국어에만 한 문장이 더 있다: EditorWindow caption(「에디터 안의 글자는 영어 그대로예요」), 오디오 가이드 확장 프로그램 설치 두 줄(엣지 버튼 이름), 오디오 에디션 AUD 스위치, 빌드 03 USB 케이블(「나머지 선은 안 써요」), 빌드 03 노브, Lab 튜토리얼 unstack[0]. 일부는 한국어 독자만 필요한 말(엣지 메뉴의 한국어 이름)이다.
• ko-short 18 — 전부 아틀라스(lib/atlas/data.ts) 의 knobEn(16)·texEn·vertEn: 영어 쪽이 AI 프롬프트에도 쓰이는 줄이라 더 길게 적혀 있다(타입 주석 그대로). 번역이 빠졌다기보다 쓰임이 다른 짝.

빠진 쪽 판정은 임시 작업 트리(지우고 나왔다)에서 일부러 짝을 깨서 확인했다 — 오늘 트리엔 빠진 쪽이 없어서:

+file,docs/foo.md,docs/foo.ko.md,50,8,ko-short
+file,docs/lonely.md,docs/lonely.ko.md,,13,missing-en
+file,firmware/patternflow/console/zz.html,firmware/patternflow/console/zz.ko.html,,7,missing-en
+file,web/content/journal/zz-only-ko.en.mdx,web/content/journal/zz-only-ko.mdx,,8,missing-en
+route,web/src/app/guide/zz/page.tsx,web/src/app/guide/zz/ko/page.tsx,,,missing-ko
+field,…features-data.ts#FEATURES[core].summary,…#FEATURES[core].summaryKo,228,4,ko-short
+field,…features-data.ts#FEATURES[audio].line,…#FEATURES[audio].lineKo,56,,missing-ko      (나머지 기능 9개도 같은 꼴)
-field,…roadmap-data.ts#NODES[pcb-proto-v0].title,…titleKo,22,8,ok
+field,…roadmap-data.ts#NODES[pcb-proto-v0].title,…titleKo,22,,missing-ko

features-data.ts 에 Ko 필드가 하나 생기면 다른 기능들이 바로 missing-ko 로 뜨고, + 로 이어 붙인 summary 도 잰다.

실행법

cd web
git fetch --tags   # 없으면 doc map 의 태그 줄 24개가 no
npm run doc-map    # 두 CSV 를 다시 쓴다

가정

• 기준 브랜치는 포크 dev, 브랜치는 세션이 정한 이름 — 계획서 D4 와 머리말대로. §2.11 의 cleanup/<step>-<name> 과 세 줄 본문은 원래 레포 PR 몫이라 세 줄은 위 절로만 넣었다. 라벨(cleanup·step-1)은 쓸 수 있는 도구가 없어 못 붙였다.
• 고친 파일은 표가 C1 에 적은 셋뿐이다. CHANGELOG.md·docs/rfc-cleanup-progress.md 는 안 고쳤다(줄은 아래 ## Changelog).
• 짝 출처를 계획서 finding 2 의 다섯보다 넓혔다. 「repo 가 유지하는 모든 짝」(§2.3)이 목표라, 같은 꼴의 짝이 있는 곳은 다 읽는다: 가이드 튜토리얼(tutorials/lab.ts·community.ts), .tsx 컴포넌트 안 문구(AudioShots·LabShots·CommunityShots·FlasherShots·ConsoleWindow·EditorWindow·LabWindow·BuildStage·desk/apps/*), 아틀라스 화면(AtlasClient.tsx), 로드맵의 LANES 라벨. 계획서 목록만으로 줄이면 copy 868줄 중 249줄과 레인 7줄이 빠진다. 언어를 삼항 연산(lang === "ko" ? … : …)으로 고르는 문구는 읽지 않는다(헤더 주석에 적었다).
• 계획서 finding 2 와 다른 점 둘: features-data.ts 엔 지금 detail 필드가 없다(line·summary) — 그래서 「Ko 필드 아무거나」로 잡게 했다. 로드맵 항목은 84 가 아니라 83 (+ 레인 7).
• 길이 비교의 2.4·40·2/3 은 위 「한 일」대로 정했다. 열엔 날 글자 수를 둬서 창작자가 판정을 다시 볼 수 있다. 같은 문장이 양쪽에 있으면 계획서에 없는 새 상태를 만들지 않고 missing-<그 언어> 로 뒀다.
• 생성된 CSV(1,367줄)는 §2.1 의 300줄 셈에서 뺐다 — D3 의 「옮긴 글」처럼 손으로 쓴 줄이 아니고 같은 명령이 다시 만든다. 손으로 쓴 줄은 doc-map.ts 의 +211/−1.
• for another lane: 없음. C3 에게 — docs/README.md 가 doc map 을 소개하는 곳이 있으면 parity CSV 한 줄을 같이 적어 주면 좋다.

Changelog

Docs

• The doc map lists the Korean/English pairs. npm run doc-map in web/ also writes docs/investigations/2026-10-doc-parity.csv: every text the repository keeps in both languages (the journal's posts, the guide's pages and copy, the roadmap, the atlas), one row per pair, with each side's length and whether one is missing or short. Korean is measured at 2.4 English characters a syllable, as the journal runs, so a faithful translation reads ok; today it flags 26 rows, among them the device's Format storage dialog, which the Korean guide quotes in English. A later x.ko.md, a console page's twin or a Ko field in features-data.ts lands in the same list.

🤖 Generated with Claude Code

https://claude.ai/code/session_01XpnQenA4LEuf6agZAbiq9y