Docs: Localization
Localization
Three languages meet in a delivered item, set on three separate channels: the language of the player's own interface, the language the content is written in, and the language alternates authored inside an item. Setting one never changes another.
Three channels
| Channel | Set by | Governs | AfA PNP 3.0 |
|---|---|---|---|
| Interface locale | The locale attribute, a deployment fact | Player status and errors, toolbar labels, tool panels, aria-labels, debug panels | language-of-interface |
| Content language | lang in the content, else the toolkit's content-language or the section
player's runtime.contentLanguage | The read-aloud voice and which catalog cards apply | Declared by the content |
| In-item alternates | Accessibility catalog cards authored in the item | Translated keywords and items, signed video | keyword-translation, item-translation, sign-language |
Interface locale
Set locale on the item player, each section player layout or the toolkit. Unset,
everything renders English. PIE ships en-US, the source catalog, and a complete nl-NL; other locales load as separate chunks, so English pages carry no other catalog.
Changing the attribute re-renders the interface in place, with no reload.
Tag resolution
Tags resolve by RFC 4647 lookup, then by widening to the primary subtag.
| Requested | Catalog | Why |
|---|---|---|
nl-NL | nl-NL | exact match |
nl_NL | nl-NL | POSIX form normalized |
nl-BE | nl-NL | primary subtag widened |
nl | nl-NL | primary subtag widened |
cy-GB | cy-GB | honored; your messages, then English |
(unset) | en-US | the browser locale is never read |
Your own messages
customMessages adds a locale or overrides shipped keys one at a time, so renaming a
label needs no fork. Plurals use Intl.PluralRules with the CLDR categories.
The players set lang and dir on their own interface subtree and leave the
document's alone. Tools registered by a host name their labels with nameKey and descriptionKey, so they localize with the rest. A coverage check in CI keeps every
shipped catalog complete.
Content language
Content language decides what read-aloud speaks in and which catalog cards apply. A lang attribute in the markup wins; content without one takes the toolkit's content-language or the section player's runtime.contentLanguage, which
default to en-US. The interface locale never sets it, so a Dutch interface can read
English content in an English voice.
| TTS provider | How the language reaches it |
|---|---|
| Browser speech | The configured voice, else a voice for the content language, else the browser's language |
| PIE TTS service (Polly, Google) | Sent as language |
| SchoolCity TTS server | Sent as lang_id |
Content language does not yet reach the elements themselves: they receive no locale through env, and the players set no lang on the content subtree. Speech-to-text
language is also not built.
In-item alternates
An item carries alternates as accessibility catalog cards, each tagged with its language. The resolver tries the content language, widening es-MX to es, then the default language, then any card of that type. A sign-language card is chosen by its card language;
PIE never infers a sign language from a spoken one and never substitutes one sign language for
another.
Accessibility catalogs cover authoring and resolution.
Element labels
Elements render their own interface text, such as button labels and feedback, in the language
named by the authored model.language. The pie-elements-ng elements ship English and
Spanish (en_US and es_ES). That channel is per item and separate from
the players' locale.
Internationalization design(opens in new tab) · Interface i18n(opens in new tab) · Section player README(opens in new tab)