#Locale Detection

Locale detection means automatically inferring which language to use when the user has not manually selected one. The plugin can detect language from URL path, Cookie, request headers, browser settings, and other sources, and these methods can be combined.

#Detection Priority

No matter which detection methods are enabled, the priority is fixed as follows, from high to low:

1. SSR data: Reads the language detected during server-side rendering from window._SSR_DATA, ensuring client and server consistency and avoiding language flicker.
2. Path detection: Reads the locale prefix from the URL path. Requires localePathRedirect.
3. i18next detector: Detects in the order configured by detection.order (Cookie, LocalStorage, query parameters, etc.).
4. initOptions.lng: A language forced by runtime configuration.
5. fallbackLanguage: The fallback language used when all detection methods fail.

#Detection Methods

#URL Path Detection

After setting localePathRedirect: true, the plugin recognizes the language from the URL path prefix and automatically redirects paths without a prefix to the default language:

/about        -> redirects to /en/about (when fallbackLanguage is en)
/zh/about     -> recognizes zh, no redirect
/en/about     -> recognizes en, no redirect

i18nPlugin({
  localeDetection: {
    localePathRedirect: true,
    languages: ['zh', 'en'],
    fallbackLanguage: 'en',
  },
});

After enabling path detection, you also need to configure a [lang] dynamic parameter in your routes. See Routing Integration.

#i18next Detector

Set i18nextDetector: true to enable language detection from Cookie, LocalStorage, query parameters, request headers, and other sources:

i18nPlugin({
  localeDetection: {
    i18nextDetector: true,
    detection: {
      order: ['cookie', 'querystring', 'header'],
      lookupCookie: 'i18next',
      lookupQuerystring: 'lng',
      lookupHeader: 'accept-language',
      caches: ['cookie'],
    },
  },
});

Both methods can be enabled at the same time:

i18nPlugin({
  localeDetection: {
    localePathRedirect: true,   // Path prefix
    i18nextDetector: true,      // Cookie / Header, etc.
    languages: ['zh', 'en'],
    fallbackLanguage: 'en',
    detection: {
      order: ['cookie', 'header'],
    },
  },
});

#Detection Options (detection)

Default detection order when order is not configured:

['querystring', 'cookie', 'localStorage', 'header', 'navigator', 'htmlTag', 'path', 'subdomain']

Available order values:

#ignoreRedirectRoutes

Specify which paths should skip locale path redirects. This is useful for API routes, static assets, and other paths that do not need a locale prefix.

Syntax 1: string array (supports exact match and prefix match)

ignoreRedirectRoutes: ['/api', '/admin', '/static']
// '/api' matches both /api and /api/users.

Syntax 2: function (more flexible custom logic)

ignoreRedirectRoutes: pathname =>
  pathname.startsWith('/api') || pathname.startsWith('/admin'),