Skip to content

armgit / dify

Public Imported from GitHub
0

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.

fix(i18n): normalize locale inputs before language selection (#42466)

yyh6024141c2684
diff --git a/web/i18n-config/README.md b/web/i18n-config/README.md
index 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 fi
4. 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 copy
diff --git a/web/i18n-config/__tests__/client-locale.spec.ts b/web/i18n-config/__tests__/client-locale.spec.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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) return
const i18n = getI18n()
- await i18n.changeLanguage(lng)
+ await i18n.changeLanguage(normalizeLocale(lng))
}
diff --git a/web/i18n-config/index.ts b/web/i18n-config/index.ts
index 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 const
export 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.ts
index 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 compatibility
export 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[] = supportedLocales
export 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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 fallback
load: 'currentOnly',
- fallbackLng: 'en-US',
+ fallbackLng: defaultLocale,
partialBundledLanguages: true,
defaultNS,
enableSelector: 'optimize',