/** * Result of resolving a user-supplied output-language string. */export interface ResolvedLanguage { /** * The canonical BCP-47 tag when the input is a recognized language, and * undefined when the input was empty or not recognized (fall back to English). * * @default undefined */ language?: string; /** * A user-facing warning, set only when a non-empty input was provided but * could not be recognized as a real language. * * @default undefined */ warning?: string;}/** * Validates and canonicalizes an output-language flag using only the built-in * Intl APIs, so no dependency is added. * * getCanonicalLocales rejects malformed tags (wrong length, digits, underscores) * by throwing, and DisplayNames distinguishes recognized codes from * structurally valid but unknown ones (for example "xx" or "english") by * echoing the input back instead of returning a real language name. * * An unrecognized value resolves to no language plus a warning, so callers fall * back to English rather than persisting or prompting with garbage. */export function resolveLanguage( input: string | null | undefined,): ResolvedLanguage { const trimmed = input?.trim(); if (!trimmed) { return {}; } try { const [canonical] = Intl.getCanonicalLocales(trimmed); const primary = new Intl.Locale(canonical).language; const displayName = new Intl.DisplayNames(["en"], { type: "language", }).of(primary); if (displayName && displayName.toLowerCase() !== primary.toLowerCase()) { return { language: canonical }; } } catch { // Malformed tag: fall through to the unrecognized-language warning. } return { warning: `Unrecognized language "${trimmed}"; generating in English. Use a BCP-47 code such as zh-CN, hi, or pt-BR.`, };}
/**
* Result of resolving a user-supplied output-language string.
*/
export interface ResolvedLanguage {
/**
* The canonical BCP-47 tag when the input is a recognized language, and
* undefined when the input was empty or not recognized (fall back to English).
*
* @default undefined
*/
language?: string;
/**
* A user-facing warning, set only when a non-empty input was provided but
* could not be recognized as a real language.
*
* @default undefined
*/
warning?: string;
}
/**
* Validates and canonicalizes an output-language flag using only the built-in
* Intl APIs, so no dependency is added.
*
* getCanonicalLocales rejects malformed tags (wrong length, digits, underscores)
* by throwing, and DisplayNames distinguishes recognized codes from
* structurally valid but unknown ones (for example "xx" or "english") by
* echoing the input back instead of returning a real language name.
*
* An unrecognized value resolves to no language plus a warning, so callers fall
* back to English rather than persisting or prompting with garbage.
*/
export function resolveLanguage(
input: string | null | undefined,
): ResolvedLanguage {
const trimmed = input?.trim();
if (!trimmed) {
return {};
}
try {
const [canonical] = Intl.getCanonicalLocales(trimmed);
const primary = new Intl.Locale(canonical).language;
const displayName = new Intl.DisplayNames(["en"], {
type: "language",
}).of(primary);
if (displayName && displayName.toLowerCase() !== primary.toLowerCase()) {
return { language: canonical };
}
} catch {
// Malformed tag: fall through to the unrecognized-language warning.
}
return {
warning: `Unrecognized language "${trimmed}"; generating in English. Use a BCP-47 code such as zh-CN, hi, or pt-BR.`,
};
}