[DONE] 한국어 가이드에서 화면 읽기 프로그램이 한국어 이름을 읽는다

[patternflow-bot]

dev / https://claude.ai/code/session_01X8JR9i3Yk2Dy8LoUDw24rn

한국어 가이드에서 화면 읽기 프로그램이 챕터 줄을 Chapters 로, 연습 책상의 알림 단추를 OK 로 읽었고, Play 와 Make 가이드의 스크린샷 60장은 그림 속 영어 단추 이름(Paste, 미리보기 셋은 다 Preview)을 alt 로 읽었어요. 이제 둘은 「챕터」, 「확인」으로 읽고, 스크린샷마다 무엇이 보이는지 읽는 사람의 언어로 말하고, English, 한국어 전환 링크는 제 언어 목소리로 읽혀요.

좋아지는 것: 한국어 가이드를 화면 읽기 프로그램이 한국어로 읽는다 — 눈으로 보지 않는 사람도 같은 말로 따라간다

• 앞 바퀴 PR([DONE] Pattern Lab 에서 매트릭스 크기를 바꾼 뒤에도 픽셀 되돌리기가 그림을 지킨다 #96–[DONE] 가이드 끝의 「다음」 링크가 사이트 안 쪽은 다시 불러오지 않고 넘어가고, 밖으로 가는 링크만 ↗ 를 달고 새 탭에서 열린다 #102) 댓글·리뷰 확인: 없음
• 챕터 줄과 알림 단추의 aria-label, 언어 전환 링크의 lang
• 스크린샷 60장의 alt 를 언어별로(Lab 26, 커뮤니티 21, 플래셔 13)
• 시험 shots.test.tsx(옛 코드에서 셋 다 실패)
• lint · typecheck · build · check:ci · check:voice
• 브라우저에서 읽기, 폰 390 · 데스크톱 1440 사진
• PR 검사 초록: Drift checks, Web CI (head f3fd2f9)

한 일

copy.ts 의 ui 에 chapters 를 더했어요. 영어는 Chapters, 한국어는 챕터예요. GuideExperience.tsx 의 ChapterRail 이 그걸 aria-label 로 받아요. 연습 책상의 알림 닫기 단추는 desk/words.ts 의 otherTabOk 에서 이름을 받아요. 영어는 그대로 OK, 한국어는 확인이에요.

언어 전환 링크(GuideExperience.tsx, GuideHub.tsx)는 글을 <span lang={other}> 로 감쌌어요. 한국어 쪽의 English 는 영어 목소리로, 영어 쪽의 한국어는 한국어 목소리로 읽혀요. GuideLink 의 lang 은 가는 쪽 언어라 HTML 의 lang 으로 내려가지 않아요.

LabShots.tsx, CommunityShots.tsx, FlasherShots.tsx 는 장면마다 alt: { en, ko } 를 둬요. 꼴은 AudioShots.tsx 를 따랐어요. 그림에 무엇이 있는지 적고, 고리가 둘러싼 곳은 marked, 표시돼 있다로 적었어요. 같은 그림을 두 장면이 쓰면(Code 탭의 Copy prompt 와 Paste) 고리 자리가 다르니 alt 도 달라요. 그림을 다 열어 보고 썼어요.

FlasherShots.tsx 는 그림을 한 번씩만 그려서, 두 줄이 같이 쓰는 그림(install-complete)은 처음 쓴 장면의 글을 alt 로 달았어요. 이제 지금 떠 있는 장면의 글을 달아요.

shots.test.tsx 는 세 보기를 두 언어로 그리고 점 단추를 하나씩 눌러, 떠 있는 그림의 alt 를 읽어요. 영어 alt 엔 한글이 없고, 한국어 alt 엔 한글이 있고, 한 줄 안에서 alt 가 겹치지 않아요. 숨은 그림은 alt 가 비고 aria-hidden 이에요.

증거

브라우저(next start, 1440)에서 읽은 것이에요. /guide/make/ko:

html lang ko · rail 챕터 · switch hreflang=en, span lang=en, English
커뮤니티 화면 순서 | 커뮤니티의 Patterns 벽, 226 PATTERNS. Newest부터 In decks까지 정렬 탭이 표시돼 있다.
패턴 랩 화면 순서 | 패턴 랩 맨 위. 빈 이름 칸에 name this pattern이 흐리게 적혀 있고, 그 아래에 Local draft가 있다.
패턴 랩 화면 순서 | Code 탭의 도구 줄과 그 아래 패턴 코드. Copy prompt 버튼이 표시돼 있다.
패턴 랩 화면 순서 | 미리보기. 검정에서 흰색으로 번지는 동심원이다.

/guide/make:

html lang en · rail Chapters · switch hreflang=ko, span lang=ko, 한국어
Pattern Lab, screen by screen | The Code tab's toolbar over the pattern's code, with the Copy prompt button marked.
Pattern Lab, screen by screen | The preview: concentric rings shading from black to white.

/guide/play/ko 와 /guide/ko 는 서버가 보낸 HTML 에서 읽었어요. 3D 무대가 있는 쪽은 스크롤로 끝까지 내려가는 데 6분 넘게 걸려 브라우저 읽기는 끊었어요.

<figure aria-label="ESP Web Tools 화면 순서">
``&lt;img src="/guide/flasher/install-dashboard.webp" alt="Patternflow라고 적힌 플래셔 창. Install Patternflow와 Logs & Console 두 가지가 있다."&gt;``
aria-label="챕터" · <span lang="en">English
/guide/ko: <a hrefLang="en" href="/guide"><span lang="en">English

눈에 보이는 건 바뀌지 않았어요. 390 사진은 alt 가 바뀐 Lab 스크린샷 띠이고, 그 그림의 alt 는 위 첫 Lab 줄이에요. 1440 사진은 쪽 맨 위예요. 가운데 챕터 줄이 이제 챕터로 읽히고, 오른쪽 위 English 가 영어로 읽혀요.

web/ 에서 돌린 명령과 각 출력의 끝줄이에요.

$ npm ci
Run `npm audit` for details.
$ npm run lint -- --max-warnings=0
> eslint --max-warnings=0          (출력 없음, 종료 0)
$ npm run typecheck
> tsc --noEmit && tsc --noEmit -p ../tools/virtual-panel          (출력 없음, 종료 0)
$ npm run build
ƒ  (Dynamic)  server-rendered on demand          (종료 0)
$ npm run check:ci
passed   virtual-panel          (roadmap 만 skipped, Vitest 43 파일 535 시험 통과, 종료 0)
$ npx vitest run src/components/guide/shots.test.tsx
      Tests  3 passed (3)
$ npm run check:voice
check:voice: nothing found

PR 검사는 head f3fd2f9 에서 Drift checks | completed | success, Web CI | completed | success 예요. dev 는 그새 움직이지 않았어요(691e5ee).

세 컴포넌트를 dev 판으로 되돌리고 같은 시험을 돌리면 셋 다 실패해요.

× LabShots > says what each screen shows in the reader's language
AssertionError: 0/0: expected 17 to be greater than 20
× CommunityShots > says what each screen shows in the reader's language
AssertionError: Newest · Oldest · Most liked · Most forked · In decks: expected 'Newest · Oldest · Most liked · Most f…' to match /\p{Script=Hangul}/u
× FlasherShots > says what each screen shows in the reader's language
AssertionError: 0/0: expected 19 to be greater than 20

실행법

web/ 에서 npm run build && npx next start -p 3100 다음 http://localhost:3100/guide/make/ko 를 열고, 개발자 도구의 Accessibility 탭에서 Pattern Lab 스크린샷의 이름을 봐요. 화면 읽기 프로그램(VoiceOver, NVDA)을 켜면 챕터 줄과 스크린샷을 한국어로 읽어요.

가정

그림 속 UI 글(Paste, Saved locally, Install Patternflow)은 alt 에서도 영어 그대로 인용했어요. 그림이 영어 UI 이고, 같은 장면의 캡션도 그렇게 해요. 한국어 alt 는 AudioShots.tsx 처럼 「…있다」로 끝내요.

연습 책상 안의 커뮤니티(desk/community/)는 진짜 사이트의 영어 UI 를 그대로 옮긴 것이라 Community sections 같은 이름도 영어예요(desk/community/words.ts 머리 주석). 그 안의 연습 안내는 쪽 언어라 상자 전체에 lang="en" 을 달 수는 없어요. 한국어 판 copy.ts 의 deviceAddress 와 install.confirm 도 영어인데, 기기 콘솔 글을 그대로 옮긴 것이라 두었어요. 책상의 iframe title="Pattern Lab" 은 이름이라 두었어요.

앞 바퀴가 고친 것은 되돌리지 않았어요. CHANGELOG.md 는 고치지 않았어요. 넣을 줄은 아래에 있어요.

Changelog

Web

• The Korean guides speak Korean to a screen reader. On the /ko pages the chapter rail was named Chapters and the practice desk's notice button OK, and the 60 screenshots in the Play and Make guides used the English control they ring as their alt (Paste, and Preview for three different previews). Each screenshot now says what it shows in the reader's language, and the English and 한국어 links carry their own lang.

바퀴

바퀴 8 · 후보 8 「한국어 가이드에서 화면 읽기 프로그램이 한국어 이름을 읽는다」

남은 것

9 「Pattern Lab 의 대화창이 Esc 로 닫히고, 위 메뉴는 터치와 키보드로도 닫힌다」: 폰에서 Panels 메뉴가 독 위에 열린 채 남아서, 4바퀴에서 고친 폰 배치를 쓰는 사람이 바로 부딪혀요.
10 「커뮤니티 창의 닫기 단추를 폰에서 누르기 쉽고, 지도의 점에 키보드 초점이 보인다」: 닫기 단추 자리가 20px 남짓이라 손가락으론 자주 빗나가요. 표의 11, 12, 13 도 아직 남았어요.
표 밖: Make 가이드의 연습 책상은 영어 UI 를 한국어 쪽에서도 lang 없이 보여 줘서, 화면 읽기 프로그램이 Newest, Send to my board 를 한국어 목소리로 읽어요. 영어 글이 든 요소마다 lang="en" 을 다는 일이라 한 바퀴 몫이에요.

🤖 Generated with Claude Code

https://claude.ai/code/session_01X8JR9i3Yk2Dy8LoUDw24rn