Build Agentic workflows, RAG pipelines, with rich AI model and tool support on one collaborative workspace. Deploy on cloud, VPC, or self-hosted, so teams move from prototype to production without rebuilding the stack.
Python agentagentic-aiagentic-frameworkagentic-workflowaiautomationclaudedeepseekgenaigptllmlow-codemcpnextjsno-codeopenaipythonskillsworkflow
fix(i18n): normalize locale inputs before language selection (#42466)
yyh6024141c2684
diff --git a/web/i18n-config/README.md b/web/i18n-config/README.mdindex 1777800acc6..385a52523a5 100644--- a/web/i18n-config/README.md+++ b/web/i18n-config/README.md@@ -5,7 +5,8 @@ English JSON files under `web/i18n/en-US/` are the source locale. Other locale d## Owners- `languages.ts` is the source of truth for supported Web locales.-- `language.ts` owns locale normalization and product-specific locale mappings.+- `locale.ts` owns canonical UI locale tags, the default locale, and input normalization.+- `language.ts` owns product-specific locale mappings.- `resources.ts` owns the typed namespace registry. File names use kebab case while namespaces use camel case, for example `app-debug.json` and `appDebug`.- `locale-resources/<locale>.ts` owns lazy loading for one locale.- `settings.ts` owns shared i18next options.@@ -21,7 +22,13 @@ Do not copy the language registry into documentation. Read the current source fi4. Keep the backend language and timezone registry in `api/constants/languages.py` aligned when the locale is accepted by backend APIs.5. Run the complete i18n check before submitting the change.-`LanguagesSupported` is populated from the supported entries in `languages.ts`. `language.ts` also owns the accepted locale spellings and the `I18nText` contract; keep them aligned when adding a locale.+`supportedLocales` is populated from the supported entries in `languages.ts`. `language.ts` exposes the existing `LanguagesSupported` and `I18nText` contracts.++## Locale selection++A nonempty locale cookie takes priority over `Accept-Language`. An unusable cookie falls back to English without consulting the header. Header negotiation preserves valid preferences and their quality order while ignoring malformed tags and wildcards.++`locale.ts` canonicalizes language tags and accepts the existing `en_US`, `zh_Hans`, and `ja_JP` spellings at input boundaries. Client language changes, saved preferences, and resource paths use supported UI tags or the English default. Share-app language overrides do not write the console locale cookie. Plugin and model metadata spellings remain separate product contracts.## Add or change copydiff --git a/web/i18n-config/__tests__/client-locale.spec.ts b/web/i18n-config/__tests__/client-locale.spec.tsnew file mode 100644index 00000000000..1f78d7eabd1--- /dev/null+++ b/web/i18n-config/__tests__/client-locale.spec.ts@@ -0,0 +1,44 @@+import Cookies from 'js-cookie'+import { setLocaleOnClient } from '..'+import { changeLanguage } from '../client'++const mocks = vi.hoisted(() => ({ changeLanguage: vi.fn() }))++vi.mock('js-cookie', () => ({ default: { set: vi.fn() } }))+vi.mock('react-i18next', () => ({ getI18n: () => ({ changeLanguage: mocks.changeLanguage }) }))++describe('client locale inputs', () => {+ beforeEach(() => {+ vi.clearAllMocks()+ mocks.changeLanguage.mockResolvedValue(undefined)+ })++ it.each([+ ['zh_Hans', 'zh-Hans'],+ ['ja_JP', 'ja-JP'],+ ['en_US', 'en-US'],+ ['ZH-hans', 'zh-Hans'],+ ['zh-Hant', 'zh-Hant'],+ ['en--US', 'en-US'],+ ['unsupported', 'en-US'],+ ])('changes and persists %s as %s', async (input, expected) => {+ await setLocaleOnClient(input, false)++ expect(Cookies.set).toHaveBeenCalledWith('locale', expected, { expires: 365 })+ expect(mocks.changeLanguage).toHaveBeenCalledWith(expected)+ })++ it('normalizes a share-app override without persisting console preferences', async () => {+ await changeLanguage('zh_Hans')++ expect(mocks.changeLanguage).toHaveBeenCalledWith('zh-Hans')+ expect(Cookies.set).not.toHaveBeenCalled()+ })++ it('preserves the current language when the app has no override', async () => {+ await changeLanguage(undefined)++ expect(mocks.changeLanguage).not.toHaveBeenCalled()+ expect(Cookies.set).not.toHaveBeenCalled()+ })+})diff --git a/web/i18n-config/__tests__/load-resource.spec.ts b/web/i18n-config/__tests__/load-resource.spec.tsnew file mode 100644index 00000000000..ca2ceb67843--- /dev/null+++ b/web/i18n-config/__tests__/load-resource.spec.ts@@ -0,0 +1,16 @@+import { loadI18nResource } from '../load-resource'++describe('locale resource loading', () => {+ it.each([+ ['en_US', 'Save'],+ ['zh_Hans', '保存'],+ ['ja_JP', '保存'],+ ['ZH-hans', '保存'],+ ['en--US', 'Save'],+ ['unsupported', 'Save'],+ ])('loads usable translations for %s', async (locale, expected) => {+ const resource = await loadI18nResource(locale, 'common')++ expect(resource.default).toMatchObject({ 'operation.save': expected })+ })+})diff --git a/web/i18n-config/__tests__/server.spec.ts b/web/i18n-config/__tests__/server.spec.tsindex 8f19d2b4a94..df1ccce8525 100644--- a/web/i18n-config/__tests__/server.spec.ts+++ b/web/i18n-config/__tests__/server.spec.ts@@ -117,4 +117,42 @@ describe('server locale', () => {await expect(getLocaleOnServer()).resolves.toBe('en-US')},)++ it.each([+ ['en_US', 'en-US'],+ ['zh_Hans', 'zh-Hans'],+ ['ja_JP', 'ja-JP'],+ ['ZH-hans', 'zh-Hans'],+ ])('normalizes the saved locale %s to %s', async (saved, expected) => {+ mocks.getCookie.mockReturnValue({ value: saved })+ const { getLocaleOnServer } = await import('../server')++ await expect(getLocaleOnServer()).resolves.toBe(expected)+ expect(mocks.headers).not.toHaveBeenCalled()+ })++ it.each(['en--US', 'en_US_invalid', '*', 'zz-ZZ'])(+ 'falls back for an unusable cookie without consulting the browser: %s',+ async (saved) => {+ mocks.getCookie.mockReturnValue({ value: saved })+ mocks.headers.mockResolvedValue(new Headers({ 'accept-language': 'ja-JP' }))+ const { getLocaleOnServer } = await import('../server')++ await expect(getLocaleOnServer()).resolves.toBe('en-US')+ expect(mocks.headers).not.toHaveBeenCalled()+ },+ )++ it.each([+ ['en--US,ja-JP;q=0.9,en-US;q=0.8', 'ja-JP'],+ ['ja-JP,en-US;q=0.8,*;q=0.5', 'ja-JP'],+ ['en-US;q=0.5,zh-CN;q=0.9', 'zh-Hans'],+ ['*,en--US;q=0.5', 'en-US'],+ ['ja-JP;q=0,en-US;q=0.5', 'en-US'],+ ])('negotiates valid header preferences from %s', async (header, expected) => {+ mocks.headers.mockResolvedValue(new Headers({ 'accept-language': header }))+ const { getLocaleOnServer } = await import('../server')++ await expect(getLocaleOnServer()).resolves.toBe(expected)+ })})diff --git a/web/i18n-config/client.ts b/web/i18n-config/client.tsindex a1b949d4997..dbc371c19dd 100644--- a/web/i18n-config/client.ts+++ b/web/i18n-config/client.ts@@ -6,6 +6,7 @@ import { createInstance } from 'i18next'import resourcesToBackend from 'i18next-resources-to-backend'import { getI18n, initReactI18next } from 'react-i18next'import { loadI18nResource } from './load-resource'+import { normalizeLocale } from './locale'import { getInitOptions } from './settings'export function createI18nextInstance(lng: Locale, resources: Resource) {@@ -25,8 +26,8 @@ export function createI18nextInstance(lng: Locale, resources: Resource) {return instance}-export const changeLanguage = async (lng?: Locale) => {+export const changeLanguage = async (lng?: string) => {if (!lng) returnconst i18n = getI18n()- await i18n.changeLanguage(lng)+ await i18n.changeLanguage(normalizeLocale(lng))}diff --git a/web/i18n-config/index.ts b/web/i18n-config/index.tsindex 2268cf2d540..3e67e9484d7 100644--- a/web/i18n-config/index.ts+++ b/web/i18n-config/index.ts@@ -2,18 +2,19 @@ import type { Locale } from '@/i18n-config/language'import Cookies from 'js-cookie'import { LOCALE_COOKIE_NAME } from '@/config'import { changeLanguage } from '@/i18n-config/client'-import { LanguagesSupported } from '@/i18n-config/language'+import { defaultLocale, normalizeLocale, supportedLocales } from './locale'export const i18n = {- defaultLocale: 'en-US',- locales: LanguagesSupported,+ defaultLocale,+ locales: supportedLocales,} as constexport type { Locale }-export const setLocaleOnClient = async (locale: Locale, reloadPage = true) => {- Cookies.set(LOCALE_COOKIE_NAME, locale, { expires: 365 })- await changeLanguage(locale)+export const setLocaleOnClient = async (locale: string, reloadPage = true) => {+ const normalized = normalizeLocale(locale)+ Cookies.set(LOCALE_COOKIE_NAME, normalized, { expires: 365 })+ await changeLanguage(normalized)if (reloadPage) location.reload()}diff --git a/web/i18n-config/language.ts b/web/i18n-config/language.tsindex 4d183acb45e..dec4f378939 100644--- a/web/i18n-config/language.ts+++ b/web/i18n-config/language.ts@@ -1,5 +1,6 @@import type { DocLanguage } from '@/types/doc-paths'import data from './languages'+import { supportedLocales } from './locale'export type I18nText = Record<(typeof LanguagesSupported)[number], string>@@ -8,9 +9,7 @@ export const languages = data.languages// for compatibilityexport type Locale = 'ja_JP' | 'zh_Hans' | 'en_US' | (typeof languages)[number]['value']-export const LanguagesSupported: Locale[] = languages- .filter((item) => item.supported)- .map((item) => item.value)+export const LanguagesSupported: Locale[] = supportedLocalesexport const getLanguage = (locale: Locale): Locale => {// Plugin metadata supports only en_US, zh_Hans, ja_JP, and pt_BR; otherwise use en_US.diff --git a/web/i18n-config/load-resource.ts b/web/i18n-config/load-resource.tsindex 214a351a31f..b767f8093b9 100644--- a/web/i18n-config/load-resource.ts+++ b/web/i18n-config/load-resource.ts@@ -1,35 +1,19 @@import type { ResourceKey } from 'i18next'-import type { Locale } from './language'import type { Namespace, NamespaceInFileName } from './resources'import { kebabCase } from 'es-toolkit/string'-import { LanguagesSupported } from './language'+import { normalizeLocale } from './locale'type LocaleResourceModule = {loadResource: (fileNamespace: string) => Promise<{ default: ResourceKey }>}-const legacyLocaleMap: Partial<Record<Locale, Locale>> = {- en_US: 'en-US',- ja_JP: 'ja-JP',- zh_Hans: 'zh-Hans',-}--const defaultLocale = 'en-US' satisfies Locale--const normalizeLocale = (locale: Locale): Locale => {- const normalized = legacyLocaleMap[locale] ?? locale- if (LanguagesSupported.includes(normalized)) return normalized-- return defaultLocale-}--const loadLocaleResources = (locale: Locale): Promise<LocaleResourceModule> => {+const loadLocaleResources = (locale: string): Promise<LocaleResourceModule> => {const normalized = normalizeLocale(locale)return import(`./locale-resources/${normalized}.ts`)}export const loadI18nResource = async (- locale: Locale,+ locale: string,namespace: Namespace | NamespaceInFileName,) => {const { loadResource } = await loadLocaleResources(locale)diff --git a/web/i18n-config/locale.ts b/web/i18n-config/locale.tsnew file mode 100644index 00000000000..0b16699b753--- /dev/null+++ b/web/i18n-config/locale.ts@@ -0,0 +1,27 @@+import data from './languages'++export type SupportedLocale = (typeof data.languages)[number]['value']++export const defaultLocale = 'en-US' satisfies SupportedLocale+export const supportedLocales = data.languages+ .filter((language) => language.supported)+ .map((language) => language.value)++const legacyLocaleMap = new Map([+ ['en_US', 'en-US'],+ ['ja_JP', 'ja-JP'],+ ['zh_Hans', 'zh-Hans'],+])++export const canonicalizeLanguageTag = (language: string): string | undefined => {+ try {+ return Intl.getCanonicalLocales(legacyLocaleMap.get(language) ?? language)[0]+ } catch {+ return undefined+ }+}++export const normalizeLocale = (language: string): SupportedLocale => {+ const canonical = canonicalizeLanguageTag(language)+ return supportedLocales.find((locale) => locale === canonical) ?? defaultLocale+}diff --git a/web/i18n-config/server.ts b/web/i18n-config/server.tsindex fe59a232774..aa6fab82c08 100644--- a/web/i18n-config/server.ts+++ b/web/i18n-config/server.ts@@ -8,9 +8,10 @@ import resourcesToBackend from 'i18next-resources-to-backend'import Negotiator from 'negotiator'import { cache } from 'react'import { initReactI18next } from 'react-i18next/initReactI18next'+import { LOCALE_COOKIE_NAME } from '@/config'import { cookies, headers } from '@/next/headers'-import { i18n } from '.'import { loadI18nResource } from './load-resource'+import { canonicalizeLanguageTag, defaultLocale, supportedLocales } from './locale'import { namespacesInFileName } from './resources'import { getInitOptions } from './settings'@@ -42,31 +43,18 @@ export async function getTranslation<T extends Namespace>(lng: Locale, ns?: T) {}export const getLocaleOnServer = cache(async (): Promise<Locale> => {- const locales: string[] = i18n.locales+ const localeCookie = (await cookies()).get(LOCALE_COOKIE_NAME)+ const requestedLanguages = localeCookie?.value+ ? [localeCookie.value]+ : new Negotiator({+ headers: { 'accept-language': (await headers()).get('accept-language') ?? '' },+ }).languages()+ const languages = requestedLanguages.flatMap((language) => {+ const canonical = canonicalizeLanguageTag(language)+ return canonical ? [canonical] : []+ })- let languages: string[] | undefined- // get locale from cookie- const localeCookie = (await cookies()).get('locale')- languages = localeCookie?.value ? [localeCookie.value] : []-- if (!languages.length) {- // Negotiator expects plain object so we need to transform headers- const negotiatorHeaders: Record<string, string> = {}- ;(await headers()).forEach((value, key) => (negotiatorHeaders[key] = value))- // Use negotiator and intl-localematcher to get best locale- languages = new Negotiator({ headers: negotiatorHeaders }).languages()- }-- // Validate languages- if (- !Array.isArray(languages) ||- languages.length === 0 ||- !languages.every((lang) => typeof lang === 'string' && /^[\w-]+$/.test(lang))- )- languages = [i18n.defaultLocale]-- // match locale- return match(languages, locales, i18n.defaultLocale) as Locale+ return match(languages, supportedLocales, defaultLocale) as Locale})export const getResources = cache(async (lng: Locale): Promise<Resource> => {diff --git a/web/i18n-config/settings.ts b/web/i18n-config/settings.tsindex 04761052ceb..a6b7400ab6f 100644--- a/web/i18n-config/settings.ts+++ b/web/i18n-config/settings.ts@@ -1,11 +1,12 @@import type { InitOptions } from 'i18next'+import { defaultLocale } from './locale'import { defaultNS, namespaces } from './resources'export function getInitOptions(): InitOptions {return {// We do not have en for fallbackload: 'currentOnly',- fallbackLng: 'en-US',+ fallbackLng: defaultLocale,partialBundledLanguages: true,defaultNS,enableSelector: 'optimize',