architectural note
i18n ∩ WCAG 2.2 AAmixed-language DOM · density · immigrant household framing
In plain English (ELI5): a screen reader is software that reads a web page aloud for people who can’t see it well. If a page mixes languages (say English and Chinese) without telling the software which is which, it reads them wrong. So I label the languages, and I leave extra room because Chinese characters take up more space than English letters. If you don’t understand assistive tech yet, learn it before you ship. Slow progress here beats a pretty page nobody can hear. This is a short, practical note, not a lecture. The same problem shows up on Serve IT (Laurie McRobbie Serve IT Nonprofit Clinic) partner pages that mix English with community languages, when a restaurant ticket switches mid-line, and when a household flips between 福州话 / 普通话 / English without thinking about it.
1 · mixed-language DOM
screen readers enunciate from language context. if chinese sits inside an english page without a language boundary, the voice engine often guesses wrong: tones flatten, names get anglicised, meaning degrades.
what i actually check
- set
langon the document root for the primary language of the page. - wrap inlined phrases in their own language with
lang="zh-Hans",lang="zh-CN", or the closest accurate BCP 47 tag. same idea for spanish study-abroad notes. - do not rely on visual bilingualism alone. a human sees two scripts; assistive tech needs the attribute.
- test the critical path with a screen reader, not only contrast checkers. serveit / rivet builds still fail here when chunks paste clean-looking text without language spans.
in cascade / rivet workflows, treat language markup as part of the chunk composition, not a late copy pass. if the chunk map cannot carry lang, document the workaround in the handoff.
2 · character density and layout
english and chinese do not share the same horizontal budget. a label that fits in 12 latin characters can explode or truncates awkwardly in han characters. buttons, nav, and table cells designed for short english verbs break when zh copy lands.
- containers need growth room: prefer wrapping over hard truncation for bilingual UI chrome.
- line-height and tracking that feel "tight and editorial" in english can crush CJK glyphs. verify both scripts at the same breakpoint.
- truncation with ellipsis is a product decision. if you must truncate, make the full string available to assistive tech (title, expandable row, or visually hidden full text).
- reflow: when zh expands a card, neighbors must not overlap. fluid grids beat fixed-width paste from a brand deck.
3 · where the instinct comes from
fuzhou roots, midwest restaurant floor. patrons, family, and staff already switch languages mid-conversation. the UI should not pretend monolingual default is neutral. immigrant household multilingualism is operational context: tickets, menu notes, and volunteer-facing pages fail loudly when language and layout ignore density.
that is the bridge-building thread on @matchaxmoxie: restaurant uptime habits applied to accessible systems. community orgs on the serveit roster (including partners like middle way house) need pages staff can maintain and visitors can hear correctly.