resolveLocale

Wählt aus den Sprachen, die du unterstützt, die passende aus — entlang der üblichen Kette: Query → Cookie → localStorage → navigator → Rückfallwert.

Der Katalog der Texte gehört dir; hier wird nur der Schlüssel gewählt.

API

resolveLocale(options)

Option	Beschreibung	Typ	Standard
`supported`	Die Sprachen, die du tatsächlich auslieferst, die genaueste zuerst	`readonly string[]`	Erforderlich
`fallback`	Wird zurückgegeben, wenn nichts passt	`string`	`supported[0]`
`query`	Abfrageparameter mit einer ausdrücklichen Wahl, etwa `lang`	`string`	—
`cookie`	Name des Cookies, das die Wahl trägt	`string`	—
`storageKey`	localStorage-Schlüssel mit der zuletzt getroffenen Wahl	`string`	—
`useNavigator`	Ob `navigator.languages` und `navigator.language` befragt werden, bevor der Rückfallwert greift	`boolean`	`true`
`url`	URL, aus der die Query gelesen wird	`string`	Der aktuelle Ort

Rückgabe

Der passende Eintrag aus supported: immer einer davon, nie eine beliebige Zeichenkette.

Beispiel

Die ganze Kette

import { resolveLocale } from 'ranuts';

const locale = resolveLocale({
  supported: ['en', 'zh-CN'],
  query: 'lang',
  cookie: 'lang',
  storageKey: 'app-lang',
});

document.documentElement.lang = locale;
render(messages[locale]);

Regionale Varianten fallen auf die Grundsprache zurück

import { resolveLocale } from 'ranuts';

const supported = ['en', 'zh-CN'];

resolveLocale({ supported, query: 'lang', url: '?lang=en-GB' }); // 'en'
resolveLocale({ supported, query: 'lang', url: '?lang=zh' }); // 'zh-CN'
resolveLocale({ supported, query: 'lang', url: '?lang=de' }); // 'en'  (nicht unterstützt → Rückfallwert)

Zusammen mit sprachbehafteten URLs

import { resolveLocale, createLocalePath } from 'ranuts';

const paths = createLocalePath({
  locales: [{ code: 'en' }, { code: 'zh-CN', prefix: 'zh' }],
});

// Was die URL schon sagt, hat Vorrang; sonst gilt die eigene Vorliebe.
const locale = paths.localeFromPath(location.pathname) ?? resolveLocale({ supported: ['en', 'zh-CN'] });

Hinweise

Auf die Reihenfolge kommt es an. Ein ?lang= in der URL ist ausdrücklich, weitergebbar und einmalig — es schlägt daher alles andere. Ein Cookie ist eine Entscheidung, die auch der Server sieht, und schlägt somit reinen Client-Zustand. localStorage ist das, was zuletzt in der Anwendung gewählt wurde. navigator.language ist bloß eine Vermutung über jemanden, der zum ersten Mal vorbeikommt. Kehrt man das um, entsteht der klassische Fehler: Ein geteilter Link mit ?lang=en wird beim Empfänger weiterhin in dessen gespeicherter Sprache dargestellt.
Das Ergebnis ist immer eines aus supported. Ein Wert außerhalb der Liste wird übergangen statt zurückgegeben; mit dem Ergebnis lässt sich also gefahrlos ein Textkatalog ansprechen.
Der Abgleich achtet nicht auf Groß- und Kleinschreibung und fällt auf die Grundsprache zurück. Bei supported: ['en', 'zh-CN'] trifft en-GB auf en und zh auf zh-CN.
navigator.languages wird der Reihe nach befragt, nicht nur navigator.language: Diese Liste ist die tatsächliche Rangfolge der Vorlieben, und ihr erster Eintrag ist oft nicht die beste verfügbare Entsprechung.
Jede Quelle zieht sich leise zurück. Kein window, kein document.cookie, kein localStorage: Jede steuert dann einfach nichts bei, sodass die Kette beim serverseitigen Rendern und in Build-Skripten funktioniert.