Internationalization

Five independent decisions #

Record these decisions explicitly. Do not derive a cultural identity or publication permission from browser language. A visitor can choose English navigation while reading content in another language.

Global word choice and local context #

Write interface messages so they do not depend on a shared local idiom, institution or unspoken convention. A locally meaningful reference can remain useful when its context is explained. Do not replace a source name, Country name or recorded language form with a generic term merely to make the interface sound global.

Prefer a concrete task and consequence over a metaphor. Keep sentences short enough to follow, but retain necessary source qualifications and permission details. This is editorial judgment; an arbitrary character limit or a synonym replacement script cannot approve meaning.

Pronouns, references and ambiguity #

Name the relevant person, record or operation when a pronoun could refer to several things. A short “this” or “that” label is not helpful if the target moves, disappears or is unclear when read outside its visual context. Keep ownership distinct from the product’s speaking role.

Clarify time, quantity, scope and sequence. A date such as 03/04 is ambiguous without a regional convention; a midnight deadline needs its date and time zone. Words such as may, later or current can hide whether an operation is permitted, possible, scheduled or already completed.

Translation handoff and semantic integrity #

• Supply complete messages, task/state context, screenshots, variable definitions, speaking role and actual action consequence. A translator should not have to infer the meaning of a detached string.
• Identify whether a variable is a display name, count, calendar date, instant, measurement or identifier. Format each according to its meaning; do not add numeric grouping to accession identifiers.
• Explain missing-variable behavior and plural/select categories in the consuming message system. Do not join translated fragments around a dynamic name.
• Keep source quotations and names separate from editable interface copy. Preserve originals and record any authorized rendition with its provenance.
• Review locale-specific punctuation, examples, tone and units with the relevant qualified people. Translating UI copy does not establish permission to publish language data.
• Use the working formatting/direction lab below and the Writing message lab to inspect layout and variable context. They do not generate translations or approve linguistic meaning.

Formatting and direction lab #

The fixed instant makes time-zone changes visible. The tool reports the browser’s resolved locale because a syntactically valid requested locale may fall back. Invalid locale/time-zone combinations pause formatting rather than presenting a fabricated result.

Bidirectional layout #

• Set direction on the appropriate document or content region. Use dir="auto" for unknown user-provided text when suitable; keep known document direction explicit.
• Use margin-inline, padding-inline, inset-inline and text-align: start. Do not reverse DOM order to imitate RTL.
• Isolate URLs, numeric identifiers and other embedded direction-sensitive content with bdi.
• Mirror directional navigation when meaning requires it. Do not mirror logos, written characters, play symbols or every image indiscriminately.
• Verify portal content inherits the intended direction; local direction on a trigger may not reach a portalled popup.

Reading direction, time and media #

Alignment and reading direction are separate. A right-aligned LTR string still reads LTR; setting text-align alone cannot repair bidi order or caret movement. Set the intended dir on the complete content or control region and isolate embedded identifiers. Preserve email username/domain order, URLs and source identifiers rather than reversing their characters.

Pair DirectionProvider with the matching DOM dir for installed composite controls: the provider supplies keyboard/navigation context, while dir supplies browser layout and text direction. A nested LTR region must override an RTL document in both contexts. A DOM ancestor selector such as [dir="rtl"] does not express that effective direction; shared directional presentation variables reset at every explicit LTR/RTL boundary and inherit through its descendants. This preserves a nested direction island without a language-name heuristic. Use explicit direction for navigation/control regions; dir="auto" is for content whose text direction is unknown. Portals require the intended provider and DOM direction at their rendered boundary.

• The Material reference notes locale exceptions for linear time/progress and charts. Record the consuming product’s task/locale decision; do not implement a universal language-name switch or infer policy from identity.
• Use Intl.DateTimeFormat parts for localized time/day-period order instead of manually moving AM/PM. A clock’s clockwise geometry is independent of its localized labels.
• The real audio pattern demonstrates an explicit LTR media control island inside its RTL surrounding layout. The icon, spacing and canonical-layout tools inspect other direction concerns; they do not certify every component or translation.

Language text and search #

• Preserve the original form alongside any normalization used for search. Do not silently strip diacritics from displayed text.
• Use Unicode-aware text operations and avoid splitting by code unit when counting user-perceived characters.
• Locale-aware sorting and case conversion need explicit policy and qualified review for the relevant language. Default English behavior is not universal.
• Avoid country flags as language selectors. A language can cross borders, and a country can contain many languages.
• Never use machine-generated Indigenous vocabulary as a specimen. Use source-attested, permitted content or an explicitly labelled user-input preview.

Messages, plurals and dates #

Use complete translation messages with an ICU-compatible plural/select mechanism in the consuming application. Give each variable a meaning and type. Keep source timestamps as instants plus the intended display time zone. A calendar-only date is a different data type and should not be shifted by timezone conversion.

const formatter = new Intl.DateTimeFormat(locale, {
  timeZone, dateStyle: "medium", timeStyle: "short",
});
const visible = formatter.format(new Date(isoInstant));

<time dateTime={isoInstant}><bdi>{visible}</bdi></time>
// locale and timeZone are explicit validated product settings.

Expansion and font coverage #

• Allow labels and help text to wrap. Avoid fixed inline widths based on English strings.
• Test a long-text locale and RTL layout independently; one does not prove the other.
• Load licensed fonts with the necessary glyphs and verify combining marks, line height and fallback.
• Set lang on known content so assistive technology can select pronunciation appropriately. Do not invent a tag when the record has no verified language identifier.

Failure cases #

• Do not use CSS text-transform to alter dictionary spelling.
• Do not parse a localized formatted date back into storage; retain structured values.
• Avoid concatenating message fragments around variables or applying English singular/plural rules everywhere.
• Do not claim Intl supports a language’s own formatting conventions merely because it accepts the locale string. Inspect resolved options and verify with speakers.

Verification #

• Change the lab to de-DE and another supported time zone; compare separators and the rendered instant.
• Enter an invalid time zone and verify the accessible error and absence of misleading formatted output.
• Enable RTL and inspect mixed-direction text, controls, focus order and portal placement.
• Review translated copy, sorting, dates and language labels with the relevant qualified reviewers. Browser formatting tests cannot verify translation or cultural appropriateness.

Related guidance #