feat(i18n): an application uses Core's translator and words Core's messages its own way

The ./i18n entry exports t, tn, msg, translateKnown and the number and date
formatters. setMessageOverrides({ en: {...}, de: {...} }) shows the
application's text for any catalog key: in the active locale, else its
English, else Core's translation.
This commit is contained in:
Sameh Khamis committed 2026-11-14 17:51:03 -08:00
1 parent b7160492e0
commit c19d82d906
5 files changed
+209 -3

No files matched your search

+74 -2
View File
@@ -177,7 +177,69 @@ function interpolate(pattern, values) {
/** A catalog string with something to show; an empty one counts as missing. */
const filled = (value) => typeof value === 'string' && value.trim() !== '';
// A host application's own text for messages Core shows (setMessageOverrides),
// by locale: { en: { 'English key': 'Its text' }, de: { … } }.
let overrides = Object.freeze({});
/**
* Show a host application's own text for Core's messages. `messages` maps a
* locale (`en` included) to entries keyed as the catalogs are: the English
* text, `context|text` for a t() context, the English plural for tn() (whose
* entry is a `{one, other, …}` object). An overridden message shows the host's
* text in the active locale, else the host's English, else Core's. Each call
* replaces the previous overrides; `{}` removes them. Call it before views
* render: onLocaleChange listeners word their text again at once, but a view
* already drawn keeps its text until it next renders. A t() entry is text, a
* tn() entry `{one, other, …}` forms worded in its locale; any other entry is
* ignored.
* @param {Record<string, Record<string, string|Record<string, string>>>} messages
*/
export function setMessageOverrides(messages) {
const next = {};
for (const [locale, entries] of Object.entries(messages ?? {})) {
const code = normalizeLocale(locale);
if (!code || !entries || typeof entries !== 'object') continue;
const own = Object.fromEntries(
Object.entries(entries).map(([key, entry]) => [
key,
entry && typeof entry === 'object'
? Object.freeze({ ...entry })
: entry,
]),
);
next[code] = Object.freeze({ ...next[code], ...own });
}
overrides = Object.freeze(next);
notifyLocaleChange();
}
/** A host's entry for t() is text; for tn() plural forms with an `other`. */
const usable = (entry, plural) =>
plural
? Boolean(entry) && typeof entry === 'object' && filled(entry.other)
: filled(entry);
/**
* The host's entry for a message, in the active locale or else in English,
* with the locale it is worded in (whose plural rules pick its form).
*/
function overridden(text, plural = false) {
for (const locale of new Set([getLocale(), DEFAULT_LOCALE])) {
const entries = overrides[locale];
const entry =
entries && Object.hasOwn(entries, text) ? entries[text] : undefined;
if (usable(entry, plural)) return { entry, locale };
}
return null;
}
function lookup(text) {
const host = overridden(text);
return host ? host.entry : catalogEntry(text);
}
/** Core's own catalog entry for a message in the active locale. */
function catalogEntry(text) {
const catalog = CATALOGS[getLocale()];
if (!catalog) return undefined;
const entry = Object.hasOwn(catalog, text) ? catalog[text] : undefined;
@@ -212,7 +274,14 @@ export function t(text, values) {
* @returns {string}
*/
export function tn(count, one, other, values) {
const entry = lookup(other);
const host = overridden(other, true);
if (host) {
const forms = host.entry;
const category = pluralRules(host.locale).select(count);
const pattern = filled(forms[category]) ? forms[category] : forms.other;
return interpolate(pattern, { count, ...values });
}
const entry = catalogEntry(other);
const category = pluralRules(getLocale()).select(count);
let pattern;
const forms = entry && typeof entry === 'object' ? entry : null;
@@ -230,8 +299,11 @@ export function tn(count, one, other, values) {
* missing-translation warning.
*/
export function translateKnown(text) {
if (typeof text !== 'string') return text;
const host = overridden(text);
if (host) return host.entry;
const catalog = CATALOGS[getLocale()];
if (!catalog || typeof text !== 'string') return text;
if (!catalog) return text;
const entry = Object.hasOwn(catalog, text) ? catalog[text] : undefined;
return filled(entry) ? entry : text;
}