Keyboard Layout API, Locale Choices, and Privacy

The WICG Keyboard Map proposal and secure-context rules define what layout knowledge a browser may expose. BotBrowser can run this interface in a controlled profile, but it cannot capture keystrokes or guarantee that every host exposes a layout map. That boundary matters when a shortcut label is useful but a layout must never become an identity signal.

TL;DR

The Keyboard Layout API can help an application label shortcut keys in the layout a user has selected. It is a presentation aid, not a keylogger, nationality detector, or proof of identity. Request the map only for a clear interface task, keep a usable fallback, and treat unavailable support as normal.

Contents

• What the layout map is for
• Permission, policy, and privacy boundaries
• Accessible labels and fallback behavior
• A testable decision rule
• Conclusion

What the layout map is for

navigator.keyboard.getLayoutMap() returns a map from physical key codes to the characters commonly produced by the active layout. A shortcut help panel can use that information to show a label that matches the user's keyboard. The map does not contain a history of keys pressed, and reading it does not grant permission to intercept input.

Keep the purpose narrow. A text editor may use a map to explain Ctrl+Z; a settings page may show the physical key behind a command. Do not turn the result into a profile field. Layouts can be shared, changed temporarily, or selected for compatibility with another person's language.

Permission, policy, and privacy boundaries

Availability depends on browser support, secure-context requirements, and policy or permission decisions. Code should handle rejection and absence without treating either as an error about the user. A failed request means the preferred label is unavailable in this context, not that the device has a suspicious or unusual identity.

The API is separate from keyboard event handling. An application still needs an explicit, task-related reason to listen for shortcuts, should avoid collecting text, and should make shortcut behavior discoverable. Do not send a layout map to a server when the browser can use it locally. If a diagnostic must record a choice, retain only the minimum data and explain its purpose.

Accessible labels and fallback behavior

Use the map to improve a label, never to hide the command's stable meaning. For example, a help row can say “Undo (Ctrl+Z)” when the map resolves the key, while the command name and an alternate pointer action remain visible. Screen-reader text should include the command and modifier names rather than exposing an unexplained code.

When the map is unavailable, use a documented default label, a command name, or a user-editable shortcut setting. Keep controls usable during a permission prompt or a layout change. Test long labels, right-to-left text, and layouts whose produced character differs from the physical key position.

A testable decision rule

1. Start with a stable command name and non-keyboard alternative.
2. In a secure context, request the layout map only when the shortcut help UI needs it.
3. If the map resolves, format a localized label in the page and do not persist the map as an identity field.
4. If it fails or is unsupported, keep the fallback and record only the product outcome needed for debugging.

This fixture gives a concrete acceptance result: a user can discover and activate “Undo” whether the map resolves or not; no test requires captured keystrokes or a particular nationality inference.

Implementation notes for a resilient control

Treat the layout map as an optional enhancement in the rendering path. The command itself should have a stable identifier, a visible name, and a pointer or touch action before any asynchronous browser capability is requested. A loading state can say that shortcut labels are being prepared, but it should never disable the command. If the request rejects, resolve to the same fallback string used when the API is absent. This makes the control deterministic for keyboard-only users and for assistive technology.

Keep capability detection narrow. Check that navigator.keyboard exists and that getLayoutMap is a function, then call it inside a user-relevant flow. Do not probe unrelated keyboard properties simply because they are available. A feature check is not evidence that a particular layout is active, and it is not permission to listen for input. Catch both synchronous type errors and asynchronous promise rejection; browser versions and policy settings can fail at either point.

Formatting deserves its own boundary. The map values are characters, not translated command names. Combine them with localized modifier names supplied by the application, and keep the command label independent from the resolved character. Avoid assuming that one character is always returned: dead keys, compose sequences, and IME behavior can produce values that need escaping or a longer description. If a value is empty or unexpected, use the documented default rather than exposing a raw code.

Testing across locales and layouts

Build a small owned fixture with three states: API unavailable, API available with a known map, and API rejected by policy or browser. Each state should render the same command and expose a status marker for the test harness. The assertion is about user-visible behavior: the command name remains present, the alternative action remains enabled, and a resolved shortcut label is an enhancement. Avoid tests that type real account data or collect a stream of key events.

Run the fixture with several explicit locale choices and at least one right-to-left writing system. Locale is an application choice and must not be inferred from the keyboard map. A user may select an English interface while using a different physical layout, or may change layouts temporarily while editing text. Test a layout change after the help panel opens; the panel should refresh its label or clearly retain the previous label without breaking activation.

For repeatable BotBrowser runs, declare the profile, host operating system, browser channel, secure-context URL, and expected fallback in the test record. A controlled profile can make the browser journey repeatable across supported systems, which is useful for comparing a candidate build with a control build. The run still describes that declared environment only. It does not establish that every host implements Keyboard Map, and it does not turn a layout observation into a customer or device identity.

Capture evidence at the same boundary as the claim. Record whether the API check passed, whether the map promise resolved, which UI state was shown, and whether the fallback action remained usable. Do not record the map itself unless a local diagnostic explicitly requires it; in most products the rendered label and an outcome code are sufficient. If diagnostics leave the browser, strip characters that could contain user-entered text and document retention.

Privacy review checklist

Before shipping, ask four questions. First, is there a user-facing reason to show a layout-dependent label? If not, omit the request. Second, can the same task be completed with a stable command name and pointer action? If yes, keep that path primary. Third, does any telemetry identify a person, device, or nationality from the map? Remove that field and retain only an aggregate product outcome. Fourth, can a policy or browser change make the request unavailable without creating an error state? Exercise the rejection path and keep it useful.

Review permission policy separately from event handling. A site may need permission policy or a secure context for the map while also handling keydown events for shortcuts. These are different capabilities with different data risks. Explain which one the interface uses, request only the required capability, and stop listening when a component unmounts. Never describe a map result as proof that a person typed a key, owns a device, speaks a language, or belongs to a region.

The same discipline applies to support tickets. A report that a shortcut label is missing should include browser support, secure-context status, policy configuration, and the fallback outcome. It should not ask the customer to send their complete layout map or a recording of their keystrokes. A minimal reproduction with a synthetic command is easier to review and avoids collecting unrelated personal data.

A compact acceptance matrix

Scenario	Expected label	Expected interaction	Data boundary
Map resolves	Localized shortcut plus command name	Keyboard and pointer actions work	Keep map local; record outcome only
API absent	Stable default label	Keyboard and pointer actions work	No capability data required
Request rejected	Stable default label and neutral status	No disabled command or retry loop	Record rejection category, not identity
Layout changes	Updated or clearly retained label	Command remains discoverable	Do not infer locale from the change
Right-to-left text	Correctly ordered accessible name	Screen reader and pointer paths work	Keep presentation separate from profile data

This matrix is intentionally modest. It tests the contract a reader can depend on rather than promising universal browser behavior. Add browser-specific cases when a supported product needs them, and label those cases with their implementation and policy assumptions.

Designing the fallback copy

Fallback text should be intentional, concise, and translated with the rest of the interface. “Undo” is usually more useful than “Key unavailable,” because it tells the reader what the control does even when no shortcut can be shown. If the product supports user-customized shortcuts, show the command first and the current shortcut second. A default such as “Undo (keyboard shortcut)” is preferable to an empty label or an implementation code. Keep punctuation and modifier order consistent with the conventions of each locale, and let the screen reader receive one coherent accessible name rather than separate fragments that may be announced in the wrong order.

Do not use the fallback as a covert capability probe. The wording should not reveal whether a particular browser, operating system, or customer profile was recognized. A neutral status such as “Keyboard shortcut labels are unavailable in this browser” is enough for a support panel; ordinary users may need no status at all. If a product has an accessibility settings page, explain that pointer activation remains available and provide a link to shortcut customization. This keeps the experience useful without asking the user to troubleshoot browser details.

Handling asynchronous updates

The map request is asynchronous, so a component can render before it resolves, after it resolves, and after the layout changes again. Use a request token or component lifetime guard so a late promise cannot update a removed dialog. When a panel closes, discard its pending presentation update. When the map changes, replace only the shortcut portion of the label and preserve focus, expanded state, and the command's click handler. Never force a re-render that moves focus to the top of a help list while a user is navigating it with a screen reader.

If the browser reports a transient failure, do not loop requests on every render. Cache a short-lived outcome for the current view, expose a manual retry only when it is useful, and continue to show the stable command. A retry must not become a permission prompt loop. For long-lived applications, refresh after an explicit layout-change signal or when the user reopens shortcut help, subject to the browser's support and policy behavior.

Documentation and support handoff

Document the capability in product terms: shortcut labels may follow the selected keyboard layout, while command semantics and non-keyboard activation remain stable. Link to the browser support reference for developers, but do not make a standards page a prerequisite for using the control. In release notes, describe changes as presentation improvements rather than new tracking or identity features. This language helps support teams answer questions without suggesting that the product observes typed content.

When escalating a defect, include the locale selected in the application, the layout chosen by the test fixture, the browser and version, whether the page was a secure context, and the visible fallback or resolved label. Include the policy response only when it is relevant to a reproducible failure. Do not include account names, typed strings, complete event logs, or a raw layout map. A synthetic “Undo” command and a public test route usually provide enough detail to reproduce the problem.

Browser and policy change management

Keyboard Map support can change as browser implementations, secure-context rules, or permission policies evolve. Pin the browser channel in repeatable tests, then run a small compatibility check against the next channel before a release. Treat a changed result as an input to review, not an automatic privacy regression. Compare the candidate and control fixtures, confirm that the fallback still works, and update public documentation only when the supported behavior is established.

The policy owner should be able to answer which response header and embedding relationship allow the feature. Application owners should be able to answer what the user sees when the feature is denied. Those responsibilities are separate. A browser automation run can observe both answers in a declared environment, but it cannot change the remote header or grant a user's permission. Keeping ownership explicit prevents a test report from being mistaken for a deployment or compliance decision.

Choosing a useful product default

For most applications, the safest default is to render the command name immediately and add a layout-aware shortcut only after it is available. This ordering keeps the first paint understandable and avoids a blank or shifting control. It also makes screenshots, translations, and automated accessibility checks stable. Teams can then compare the enhanced label with the fallback in a normal product review: both should identify the same action, and both should remain usable when a browser declines the request.

The decision is especially important in shared workstations, classrooms, and multilingual support environments. A selected layout can reflect a temporary task rather than a person, organization, or country. Let the person choose an application locale explicitly, and let the browser map improve shortcut presentation locally. Keeping those choices separate gives users predictable controls and gives support staff a clear explanation when a label differs from one machine to another.

Conclusion

Keyboard mapping can make controls clearer across language and hardware layouts, but it should remain a bounded presentation input. Separate layout labels from event collection, permissions, account locale, and identity decisions. For repeatable cross-host review, BotBrowser can carry a controlled profile across supported operating systems; it does not capture keystrokes or guarantee that every host exposes a layout map.

Read the Keyboard Map specification, MDN Keyboard API, and cross-platform profile guide. For adjacent localization boundaries, see the Intl locale formatting guide and timezone and language guide.

Public sources

• WICG Keyboard Map
• MDN: Keyboard API
• MDN: Keyboard.getLayoutMap()