Accessibility and Internationalization

A product is only as big as the people who can use it. This guide shows how to make a frontend work for users with disabilities and for users in any language. It names the browser APIs and standards behind each choice.

Frontend system design · Foundations · Accessibility and i18n

After this guide you can design components that work with a keyboard and a screen reader. You can explain WCAG 2.2 levels and plan focus, live regions, contrast, and motion. You can also design an i18n pipeline with ICU messages, Intl APIs, RTL layouts, and per-locale bundle loading.

Correctness contract: every action is possible with a keyboard alone. Every control has a correct name, role, and state in the accessibility tree. Every user-facing string, number, and date is shown in the user's locale and direction.

Assumptions: a React-style single-page app, a design system shared across teams, and a target of WCAG 2.2 level AA. The product ships in 20 or more locales, including Arabic and Hebrew.

Accessibility (a11y) and internationalization (i18n) look like separate topics. In practice they share one root idea. The person using your UI is not you. They may not see the screen, use a mouse, read English, or read left to right. Both are cheap when built in early and costly to retrofit. Interviewers at senior and staff level expect you to raise both without being asked, and to name real APIs, not just good intentions.

Contents

  1. Concepts to understand first
  2. 1. Semantic HTML first
  3. 2. ARIA roles, states, and properties
  4. 3. Keyboard navigation and focus management
  5. 4. Focus traps for dialogs
  6. 5. Live regions
  7. 6. Color contrast, reduced motion, and zoom
  8. 7. WCAG 2.2 levels and testing
  9. 8. String externalization and ICU messages
  10. 9. Intl APIs for dates, numbers, and lists
  11. 10. RTL layouts and logical CSS
  12. 11. Fonts and text expansion
  13. 12. Loading translations per locale
  14. 13. Failure modes
  15. 14. Trade-offs
  16. 15. Interview angle
  17. 16. Summary
  18. 17. Common mistakes
  19. Worked example: an accessible, localized delete dialog
  20. Code lab: a tiny ICU-style plural formatter with Intl
  21. Check yourself
  22. Key terms
  23. Further reading

Concepts to understand first

Accessibility tree

The browser builds an accessibility tree next to the DOM. Each node has a role, an accessible name, states, and a value. Screen readers read this tree through the operating system's accessibility API. They never see your CSS classes.

Example. <button>Save</button> becomes a node with role "button" and name "Save". A <div class="btn">Save</div> becomes plain text with no role.

Limit. The tree only reflects what you express in markup. Visual meaning, such as red for error, is lost unless you add text or ARIA.

Accessible name

The accessible name is what a screen reader says for a control. The browser computes it in a fixed order. It tries aria-labelledby, then aria-label, then native labels like <label for> or alt, then text content.

Example. An icon button with only an SVG has no name. Screen readers say "button". Adding aria-label="Close" fixes it.

Limit. aria-label is often not translated by browser translation tools. Prefer visible text or aria-labelledby pointing at visible text.

Focus and tab order

Focus marks the element that receives keyboard input. Tab order follows DOM order for focusable elements. tabindex="0" adds an element to that order. tabindex="-1" makes it focusable by script only.

Example. After a route change in an SPA, focus stays on the old link, which no longer exists. Moving focus to the new page's <h1> tells keyboard and screen reader users where they are.

Limit. Positive tabindex values such as tabindex="5" break the natural order. Avoid them.

Locale

A locale is a language plus region and options, written as a BCP 47 tag like pt-BR or ar-EG-u-nu-latn. It controls words, plural rules, number and date formats, sorting, and text direction.

Example. One million is 1,000,000 in en-US, 1.000.000 in de-DE, and 10,00,000 in en-IN.

Limit. Language and region are separate choices. A user in Germany may want English text with euro prices and German dates.

Plural categories

Languages group numbers into plural categories. Unicode CLDR defines six: zero, one, two, few, many, other. English uses two. Arabic uses all six. Japanese uses one.

Example. In Polish, 2 files is "2 pliki" (few) and 5 files is "5 plików" (many). Code like count === 1 ? 'file' : 'files' is wrong for Polish.

Limit. Plural rules cover numbers only. Gender and grammatical case need select messages too.

1. Semantic HTML first

The first rule of ARIA is "do not use ARIA if a native element does the job". Native elements come with roles, names, states, focus, and keyboard behavior for free. They also work in every screen reader, which custom widgets often do not.

What native elements give you

Images and icons

Intuition

Semantic HTML is a contract with the browser. You say "this is a button", and the browser handles focus, keys, and announcements. A styled div breaks the contract, and you must write all of that by hand.

2. ARIA roles, states, and properties

WAI-ARIA adds attributes that change the accessibility tree. It never changes behavior. Adding role="button" does not make an element focusable or clickable by keyboard. ARIA is a promise to assistive technology. Your code must keep that promise.

The three kinds of ARIA attribute

A combobox example

An autocomplete input is one of the hardest widgets. The WAI-ARIA Authoring Practices pattern looks like this:

<label id="city-label" for="city">City</label>
<input id="city" role="combobox" aria-autocomplete="list"
       aria-expanded="true" aria-controls="city-list"
       aria-activedescendant="city-opt-2">
<ul id="city-list" role="listbox" aria-labelledby="city-label">
  <li id="city-opt-1" role="option">Berlin</li>
  <li id="city-opt-2" role="option" aria-selected="true">Bern</li>
</ul>

Rules that prevent most ARIA bugs

Mistake

"More ARIA means more accessible." WebAIM scans the top one million home pages each year. Pages with ARIA have more detected errors on average than pages without it. Wrong ARIA is worse than none.

3. Keyboard navigation and focus management

Many users rely on a keyboard: blind users with screen readers, users with tremors, power users, and users of switch devices that emulate keys. WCAG requires that every function works from a keyboard, with no keyboard traps.

Standard key expectations

Roving tabindex

A toolbar with 12 buttons should be one tab stop, not twelve. The roving tabindex pattern gives the active item tabindex="0" and all others tabindex="-1". Arrow keys move the zero and call focus() on the new item. Tab leaves the whole widget in one step. The alternative is aria-activedescendant, where focus stays on the container. Use roving tabindex when items are real buttons. Use aria-activedescendant when focus must stay in an input, as in a combobox.

Focus management in SPAs

Visible focus

Never remove focus outlines with outline: none without a replacement. Use :focus-visible. It shows the ring for keyboard users but not after a mouse click. WCAG 2.2 adds 2.4.11 Focus Not Obscured, which says sticky headers and cookie banners must not fully cover the focused element.

Tip

Test every new screen by unplugging the mouse for five minutes. Can you reach every control? Can you see where focus is? Does Escape close what you opened? Most keyboard bugs show up in that short test.

4. Focus traps for dialogs

A modal dialog must keep focus inside itself until it closes. Otherwise Tab moves into the page behind, which sighted users cannot see and screen reader users find confusing.

Components derive UI state, render DOM with ARIA attributes, the browser computes the accessibility tree, the OS accessibility API exposes it to screen readers. Keyboard events flow back into state, and a focus manager moves focus on open and close.
From component to screen reader. State drives ARIA attributes and focus. The browser turns both into the accessibility tree.

The native way

The <dialog> element with dialog.showModal() does most of the work. The browser makes everything outside the dialog inert, so it cannot be focused or clicked. It moves focus into the dialog, closes on Escape with a cancel event, and renders in the top layer above all z-index stacks. It does not return focus to the trigger in every browser. Do that yourself on close.

The checklist for any modal

  1. Give it role="dialog" (or alertdialog for urgent confirms) and aria-modal="true". A native modal <dialog> has these already.
  2. Name it with aria-labelledby pointing at its heading. Describe it with aria-describedby if there is a short message.
  3. On open, move focus to the first useful control. For a destructive confirm, focus the safe choice, such as "Cancel".
  4. Keep Tab and Shift+Tab inside. Use the inert attribute on the rest of the page, or loop focus from the last to the first focusable element.
  5. Close on Escape. Return focus to the element that opened the dialog.
  6. Stop background scroll, but do not hide the background from screen readers with aria-hidden if you already use inert.

The inert attribute is now in all major browsers. Setting inert on the page wrapper removes it from focus order and from the accessibility tree in one step. It replaces fragile focus-loop scripts and aria-hidden toggling.

Mistake

Trapping focus in something that is not modal. A non-modal side panel or toast must not trap focus. Users must be able to Tab out. Traps are only for modal dialogs that block the page.

5. Live regions

Screen readers announce focus changes. They do not announce changes elsewhere on the page. A toast, a form error, or "3 new messages" is silent unless it is in a live region.

Rules that make live regions work

6. Color contrast, reduced motion, and zoom

Contrast

Reduced motion

Large motion such as parallax, zooming transitions, and auto-playing carousels can cause nausea for people with vestibular disorders. Respect the OS setting with the prefers-reduced-motion media query.

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
    scroll-behavior: auto !important;
  }
}

Zoom, reflow, and target size

7. WCAG 2.2 levels and testing

Structure and levels

WCAG is organized under four principles, often remembered as POUR: Perceivable, Operable, Understandable, Robust. Each success criterion has a level.

WCAG 2.2 became a W3C Recommendation in October 2023. It added nine criteria. Key ones for frontend engineers are Focus Not Obscured (2.4.11, AA) and Dragging Movements (2.5.7, AA), which needs a non-drag alternative. Others are Target Size Minimum (2.5.8, AA) and Redundant Entry (3.3.7, A). Accessible Authentication (3.3.8, AA) bans puzzles and memory tests unless paste or passkeys work too. It also removed 4.1.1 Parsing as obsolete. Laws such as the European Accessibility Act, in force since June 2025, and the ADA in the US make AA a business requirement.

Testing in layers

Tip

Learn five VoiceOver commands: Cmd+F5 to start, VO+Right Arrow to move, VO+U for the rotor, VO+Space to activate, and Ctrl to stop speech. VO is Ctrl+Option. Ten minutes a week is enough to catch most naming and announcement bugs.

8. String externalization and ICU messages

Internationalization (i18n) is the engineering work that makes localization (l10n) possible. Localization is the translation and cultural adaptation itself. Good i18n means a translator can ship a new language without an engineer touching code.

Externalize every string

ICU MessageFormat

ICU MessageFormat is the standard syntax for messages with variables, plurals, and selection. Libraries like FormatJS (react-intl), i18next with an ICU plugin, and Lingui use it.

{count, plural,
  =0 {Your cart is empty}
  one {You have # item in your cart}
  other {You have # items in your cart}
}

{gender, select,
  female {{name} added you to her team}
  male {{name} added you to his team}
  other {{name} added you to their team}
}

Precompile messages

Parsing ICU strings at runtime costs CPU and needs a parser in the bundle, about 10 to 15 KB gzipped. Tools like @formatjs/cli compile turn messages into an AST or functions at build time. The runtime then only formats. MessageFormat 2.0, a newer Unicode standard, is coming to browsers as Intl.MessageFormat. Watch it, but ship with a library today.

Mistake

Writing count === 1 ? 'item' : 'items'. It is wrong for Russian, Polish, Arabic, Welsh, and many more. Always route counts through plural rules.

9. Intl APIs for dates, numbers, and lists

The browser ships CLDR locale data through the Intl namespace. It costs zero bundle bytes and covers hundreds of locales. Use it instead of Moment.js locale files or hand-written formats.

Practical rules

10. RTL layouts and logical CSS

Arabic, Hebrew, Persian, and Urdu read right to left. More than 500 million people use these scripts. RTL support is more than flipping text. The whole layout mirrors: navigation moves to the right, back arrows point right, and progress bars fill from the right.

Set direction at the root

Use logical properties

Physical CSS like margin-left and text-align: right is tied to the screen. Logical properties are tied to the reading direction, so one stylesheet works for both.

/* physical, breaks in RTL */
.card { margin-left: 16px }
.card { padding-right: 8px }
.card { text-align: left }

/* logical, works in both */
.card { margin-inline-start: 16px }
.card { padding-inline-end: 8px }
.card { text-align: start }
.card { inset-inline-start: 0 }
Tip

Add a pseudo-locale to your dev build. It wraps each string in brackets, adds accents, and grows it by 40 percent: [Šåvé çhåñĝéš ~~~~]. Add an RTL pseudo-locale too. You will see hard-coded strings, clipped text, and physical CSS on day one.

11. Fonts and text expansion

Text expansion

Translations are often longer than English. German and Finnish words can be very long, and short UI labels grow the most.

Design for it. Avoid fixed widths on buttons and tabs. Let text wrap. Use min-width, not width. Add overflow-wrap: anywhere or hyphens: auto (which needs a correct lang) for long words. Truncation with text-overflow: ellipsis is a last resort. If you truncate, show the full text in a tooltip and keep it in the accessible name.

Fonts across scripts

12. Loading translations per locale

A product with 40 locales and 8,000 strings can have 40 catalogs of 300 KB each. Shipping all of them to every user would cost 12 MB. Load only the user's locale, and only the strings the current route needs.

Strings are extracted from source at build, translated, and published as hashed per-locale bundles on a CDN. The edge picks the locale from Accept-Language or a cookie. The client imports the bundle, formats with Intl APIs, and sets lang and dir on the html element.
The i18n pipeline. Strings leave the code at build time and come back per locale and per route at runtime.

Choosing the locale

  1. Use an explicit user choice first, saved in the account or a cookie.
  2. Then a locale in the URL, such as /de/ or de.example.com. URL locales are best for SEO and shareable links. Add <link rel="alternate" hreflang="de"> tags.
  3. Then the Accept-Language header on the server, or navigator.languages in the client.
  4. Match against supported locales with fallback: pt-BR to pt to the default. Intl.getCanonicalLocales and the Intl.Locale object help parse tags.

Delivering catalogs

Interview

Give numbers. "We have 6,000 strings in 30 locales. Each route needs about 400 strings, or 12 KB gzipped. We inline them with SSR and cache the rest per route. The full catalog never ships." That shows you treat translations as part of the performance budget.

13. Failure modes

14. Trade-offs

15. Interview angle

In a design interview, accessibility and i18n usually get 5 to 8 minutes. Use them well.

  1. Minute 0 to 1. State the targets: WCAG 2.2 AA, keyboard and screen reader support, and the locale list including any RTL language.
  2. Minute 1 to 3. Name the hardest widget in the design, such as a combobox, a grid, or a drag-and-drop board. Describe its roles, keys, and focus rules. For drag and drop, give a keyboard alternative, as WCAG 2.5.7 requires.
  3. Minute 3 to 4. Cover dynamic updates: route-change focus, live regions, and focus return after dialogs.
  4. Minute 4 to 6. Cover i18n: ICU messages with plurals, Intl formatters, logical CSS for RTL, and room for 30 to 300 percent text growth.
  5. Minute 6 to 8. Cover delivery and checks: per-route catalogs, axe in CI, role-based test queries, and manual screen reader passes.
Interview

A staff-level answer puts both topics in the design system. "Our Dialog, Menu, and Combobox components own focus and ARIA. Our lint blocks raw strings and physical CSS. Product teams get accessibility and RTL by default."

16. Summary

17. Common mistakes

Worked example: an accessible, localized delete dialog

A user on a files page selects 3 files and presses Delete. The UI is in Egyptian Arabic, ar-EG. The user uses NVDA with a keyboard.

  1. The page is served as <html lang="ar" dir="rtl">. The Arabic catalog for the files route was inlined in the HTML, about 9 KB gzipped.
  2. Focus is on the "Delete" toolbar button. The toolbar uses roving tabindex, so this button has tabindex="0". The app saves a reference to it as the return target.
  3. The app calls dialog.showModal() on a native <dialog> with role="alertdialog", since this is a destructive confirm. The browser makes the rest of the page inert.
  4. The title is formatted with ICU: {count, plural, one {...} two {...} few {حذف # ملفات؟} ...}. Intl.PluralRules('ar-EG').select(3) returns few. The # becomes "٣", because ar-EG uses Arabic-Indic digits.
  5. The dialog has aria-labelledby on the title and aria-describedby on the message "This cannot be undone" in Arabic.
  6. Focus moves to "Cancel", the safe choice. NVDA reads the dialog role, the title, the description, and then "Cancel, button".
  7. Logical CSS places the buttons. margin-inline-start puts "Cancel" on the right, the start side in RTL. No RTL-specific stylesheet is needed.
  8. The user presses Tab, then Shift+Tab. Focus moves between "Delete" and "Cancel" and never leaves the dialog, because the page behind is inert.
  9. The user presses Enter on "Delete". The app closes the dialog, sends the request, and returns focus. The original button is gone because the toolbar hides it with no selection. So focus moves to the file list heading instead.
  10. When the server confirms, the shared announcer sets the polite live region text to the Arabic for "3 files deleted". NVDA speaks it after it finishes reading the heading.
  11. The deleted-at time in the trash view uses Intl.RelativeTimeFormat('ar-EG', { numeric: 'auto' }), which gives the Arabic word for "now".

Every step used built-in browser features: <dialog>, inert, live regions, logical CSS, and Intl. The custom code was small: save and return focus, and call the announcer.

Code lab: a tiny ICU-style plural formatter with Intl

This lab builds a small formatter for ICU plural messages. It supports =N exact matches, CLDR categories, and # with locale-aware numbers. It caches formatters, as the guide recommends. Save as plural.mjs and run node plural.mjs with Node 18 or newer, which ships full ICU data. It also runs in any browser console.

const cache = new Map()
function cached(kind, locale, opts = {}) {
  const key = `${kind}|${locale}|${JSON.stringify(opts)}`
  if (!cache.has(key)) cache.set(key, new Intl[kind](locale, opts))
  return cache.get(key)
}

// branches: { '=0': '...', one: '...', few: '...', other: '...' }
export function formatPlural(locale, count, branches) {
  const exact = branches[`=${count}`]
  const category = cached('PluralRules', locale).select(count)
  const text = exact ?? branches[category] ?? branches.other
  if (text === undefined) throw new Error(`no branch for ${category} in ${locale}`)
  return text.replaceAll('#', cached('NumberFormat', locale).format(count))
}

const RTL = new Set(['ar', 'he', 'fa', 'ur'])
export const dirFor = (locale) => (RTL.has(new Intl.Locale(locale).language) ? 'rtl' : 'ltr')

const messages = {
  en: { '=0': 'No files', one: '# file', other: '# files' },
  pl: { one: '# plik', few: '# pliki', many: '# plików', other: '# pliku' },
  'ar-EG': { zero: 'لا ملفات', one: 'ملف واحد', two: 'ملفان', few: '# ملفات', many: '# ملفًا', other: '# ملف' },
}

for (const [locale, branches] of Object.entries(messages)) {
  const out = [0, 1, 2, 3, 5, 22, 1500].map((n) => formatPlural(locale, n, branches))
  console.log(locale, dirFor(locale), '|', out.join(' | '))
}

const list = cached('ListFormat', 'es', { type: 'conjunction' })
console.log(list.format(['rojo', 'verde', 'azul']))
console.log(cached('RelativeTimeFormat', 'de', { numeric: 'auto' }).format(-1, 'day'))

Look at the output. Polish picks few for 2, 3, and 22, and many for 5. Arabic uses all six categories, and ar-EG prints Arabic-Indic digits. English uses the =0 exact branch for zero. The last two lines print "rojo, verde y azul" and "gestern". Try adding ru with one, few, many, and other branches to see Russian rules.

Check yourself

  1. Why is <div role="button"> not enough to make a working button?
    Answer

    ARIA only changes the accessibility tree. The div is still not focusable and does not respond to Enter or Space. You would need tabindex="0" and key handlers. A native <button> gives all of it for free.

  2. A toast says "Saved" but screen reader users never hear it. What are two likely causes?
    Answer

    The toast is not in a live region, or the live region was inserted into the DOM together with its text. The region must exist before the change. Another cause is an assertive region interrupting it.

  3. When would you use aria-activedescendant instead of roving tabindex?
    Answer

    When real focus must stay on one element while the user moves through options. A combobox is the classic case, because the user keeps typing. Roving tabindex moves real focus, which fits toolbars, tabs, and menus.

  4. Why is count === 1 ? 'file' : 'files' wrong for a global product?
    Answer

    Many languages have more than two plural forms. Polish, Russian, and Arabic pick different forms for 2, 5, or 11. Use ICU plural messages backed by Intl.PluralRules.

  5. Why use margin-inline-start instead of margin-left?
    Answer

    Logical properties follow reading direction. In RTL, margin-inline-start becomes a right margin with no extra CSS. Physical properties need a separate RTL override for every rule.

  6. Name three WCAG 2.2 additions that affect frontend code.
    Answer

    Focus Not Obscured (2.4.11), Dragging Movements alternative (2.5.7), Target Size Minimum of 24 by 24 px (2.5.8), and Accessible Authentication (3.3.8). Any three of these are correct.

  7. How do you avoid shipping 12 MB of translations?
    Answer

    Load only the user's locale, split catalogs by route, precompile messages, cache hashed files forever, and inline the first route's strings with SSR.

Key terms

Accessibility tree
The browser's model of the page for assistive technology, with role, name, state, and value per node.
Accessible name
The text a screen reader says for an element, computed from labels, ARIA, and content.
WAI-ARIA
Attributes that add roles, states, and properties to the accessibility tree.
Roving tabindex
A pattern where one item in a widget has tabindex="0" and arrow keys move it.
Focus trap
Keeping keyboard focus inside a modal dialog until it closes.
inert
An HTML attribute that removes a subtree from focus, clicks, and the accessibility tree.
Live region
An element whose changes screen readers announce, set with aria-live or roles like status.
WCAG
Web Content Accessibility Guidelines. Success criteria at levels A, AA, and AAA.
ICU MessageFormat
A message syntax with placeholders, plural, select, and selectordinal branches.
CLDR
Unicode Common Locale Data Repository. The source of plural rules and formats behind Intl.
Logical properties
CSS properties like margin-inline-start that follow writing direction.
Pseudo-locale
A fake locale that marks, accents, and lengthens strings to find i18n bugs.

Further reading

Primary references