Language choice

Who decides the reader's language, how a request is matched against your language set, and how a switch is stored.

@workspace/active-i18n 1.1.0Developmentunreleased, in development in Foundationbaseline ce081dc3

Your application decides the language. The package reads no cookie, no header and no setting by itself; you resolve the language and pass it in. It helps with the matching and with the switch.

Matching a request against your set#

import {  lookupFirstSupportedLocale,  lookupSupportedLocale,} from '@workspace/active-i18n';
lookupSupportedLocale('en-GB', ['en', 'nl']); // 'en' (truncated one subtag at a time)lookupSupportedLocale('pt', ['pt-BR']); // undefined: never more specificlookupFirstSupportedLocale(['de-CH', 'fr'], ['de', 'fr']); // 'de'

This is RFC 4647 lookup, not a negotiation engine: no best fit, no likely subtags, no sibling region. What follows a miss (your fallback language) is yours.

In a Next request, getAcceptLanguageCandidates() from @workspace/active-i18n/server/get-locale gives the Accept-Language header as canonical tags in priority order, unfiltered; pass them to lookupFirstSupportedLocale.

Switching the language#

<I18nProvider> never changes language in memory. setLocale(code) (from useLocaleSwitcher):

1. asks your confirmLocaleSwitch guard, when given (a page with unsaved work says no);
2. hands the choice to your persistLocale, when given (a cookie, a profile);
3. sets <html lang> and navigates, so the server renders the new language.

It resolves to a LocaleSwitchOutcome and never throws: 'switched', 'declined', 'persist-failed', 'pending' (a switch already under way), 'navigation-guarded' and others.

The language set#

Each entry of supportedLanguages is a LanguageConfig: code, label and optionally direction. Show a language by its own name, never by a flag: the package reads no flag and no switcher may show one.