refactor!: functions in the config to be used through hooks

docs/content/2.guide/15.migrating.md

@@ -149,6 +149,10 @@ About details, See also [Lang Switcher](/api/lang-switcher#dynamic-route-paramet
 
 This option is no longer necessary, because i18n custom block is supported by [unplugin-vue-i18n](https://github.com/intlify/bundle-tools/tree/main/packages/unplugin-vue-i18n) **as default**.
 
+### Deprecated `onBeforeLanguageSwitch` and `onLanguageSwitched` function options
+
+These functions can now be triggered using Nuxt runtime hooks. Please refer to [runtime hooks](/guide/runtime-hooks) to see how to use these.
+
 ### Change some export APIs name on Nuxt context
 
 The following API will be changed to `$`:

docs/content/2.guide/2.callbacks.md → docs/content/2.guide/2.runtime-hooks.md

@@ -1,25 +1,25 @@
-# Callbacks
+# Runtime Hooks
 
-Nuxt i18n module exposes some callbacks that you can use to perform specific tasks that depend on the app's language.
+Nuxt i18n module exposes some [runtime hooks](https://nuxt.com/docs/guide/going-further/hooks#app-hooks-runtime) as callbacks that you can use to perform specific tasks that depend on the app's language.
 
 ---
 
 **Nuxt i18n module** exposes some callbacks that you can use to perform specific tasks that depend on the app's language.
 
-### `onBeforeLanguageSwitch`
+### `i18n:beforeLocaleSwitch`
 
 Called before the app's locale is switched. Can be used to override the new locale by returning a new locale code.
 
 Parameters:
 
 - **oldLocale**: the app's locale before the switch
 - **newLocale**: the app's locale after the switch
-- **isInitialSetup**: set to `true` if it's the initial locale switch that triggers on app load. It's a special case since the locale is not technically set yet so we're switching from no locale to locale.
-- **nuxtApp**: the Nuxt app
+- **initialSetup**: set to `true` if it's the initial locale switch that triggers on app load. It's a special case since the locale is not technically set yet so we're switching from no locale to locale.
+- **context**: the Nuxt app
 
 Returns: `string` or nothing
 
-### `onLanguageSwitched`
+### `i18n:localeSwitched`
 
 Called right after the app's locale has been switched.
 
@@ -34,13 +34,14 @@ A typical usage would be to define those callbacks via a plugin where you can ac
 
 ```js {}[/plugins/i18n.js]
 export default defineNuxtPlugin(nuxtApp => {
- // onBeforeLanguageSwitch called right before setting a new locale
- nuxtApp.$i18n.onBeforeLanguageSwitch = (oldLocale, newLocale, isInitialSetup, nuxtApp) => {
- console.log('onBeforeLanguageSwitch', oldLocale, newLocale, isInitialSetup)
- }
- // onLanguageSwitched called right after a new locale has been set
- nuxtApp.$i18n.onLanguageSwitched = (oldLocale, newLocale) => {
+ // called right before setting a new locale
+ nuxtApp.hook('i18n:beforeLocaleSwitch', ({ oldLocale, newLocale, initialSetup, context }) => {
+ console.log('onBeforeLanguageSwitch', oldLocale, newLocale, initialSetup)
+ })
+
+ // called right after a new locale has been set
+ nuxtApp.hook('i18n:localeSwitched', ({oldLocale, newLocale}) => {
  console.log('onLanguageSwitched', oldLocale, newLocale)
- }
+ })
 })
 ```

docs/content/3.options/2.routing.md

@@ -113,24 +113,6 @@ Whether [custom paths](/guide/custom-paths) are extracted from page files
 
 If `customRoutes` option is disabled with `config`, the module will look for custom routes in the `pages` option. Refer to the [Routing](/guide/routing-strategies) for usage.
 
-## `onBeforeLanguageSwitch`
-
-- type: `function`
-- default: `(oldLocale, newLocale, isInitialSetup, context) => {}`
-
-A listener called before the app's locale is changed. Can override the locale that is about to be set.
-
-See [callbacks](/guide/callbacks)
-
-## `onLanguageSwitched`
-
-- type: `function`
-- default: `(oldLocale, newLocale) => {}`
-
-A listener called after app's locale has changed.
-
-See [callbacks](/guide/callbacks)
-
 ## `skipSettingLocaleOnNavigate`
 
 - type: `boolean`

docs/content/4.API/3.vue-i18n.md

@@ -102,15 +102,3 @@ Object of the current locale properties.
 - **Type**: `boolean`
 
 Whether `differentDomains` option is enabled.
-
-### onBeforeLanguageSwitch
-
-- **Type**: `Function`
-
-See [callbacks](/guide/callbacks)
-
-### onLanguageSwitched
-
-- **Type**: `Function`
-
-See [callbacks](/guide/callbacks)

playground/nuxt.config.ts

@@ -78,12 +78,6 @@ export default defineNuxtConfig({
  // // // cookieKey: 'my_custom_cookie_name',
  // // redirectOn: 'root'
  // },
- onBeforeLanguageSwitch: (oldLocale: string, newLocale: string, initial: boolean, nuxt: NuxtApp) => {
- console.log('onBeforeLanguageSwitch', oldLocale, newLocale, initial)
- },
- onLanguageSwitched: (oldLocale: string, newLocale: string) => {
- console.log('onLanguageSwitched', oldLocale, newLocale)
- },
  // vueI18n: './vue-i18n.options.ts'
  vueI18n: {
  legacy: false,

playground/plugins/i18n.ts

@@ -1,11 +1,11 @@
 import { defineNuxtPlugin } from '#imports'
 
 export default defineNuxtPlugin(nuxtApp => {
- nuxtApp.$i18n.onBeforeLanguageSwitch = (oldLocale, newLocale, isInitialSetup, nuxtApp) => {
- console.log('onBeforeLanguageSwitch', oldLocale, newLocale, isInitialSetup)
- }
- // onLanguageSwitched called right after a new locale has been set
- nuxtApp.$i18n.onLanguageSwitched = (oldLocale, newLocale) => {
+ nuxtApp.hook('i18n:beforeLocaleSwitch', ({ oldLocale, newLocale, initialSetup }) => {
+ console.log('onBeforeLanguageSwitch', oldLocale, newLocale, initialSetup)
+ })
+
+ nuxtApp.hook('i18n:localeSwitched', ({ oldLocale, newLocale }) => {
  console.log('onLanguageSwitched', oldLocale, newLocale)
- }
+ })
 })

specs/fixtures/plugins/i18nHooks.ts

@@ -0,0 +1,15 @@
+import { defineNuxtPlugin } from '#imports'
+
+export default defineNuxtPlugin(nuxtApp => {
+ nuxtApp.hook('i18n:beforeLocaleSwitch', ({ oldLocale, newLocale, initialSetup }) => {
+ console.log('onBeforeLanguageSwitch', oldLocale, newLocale, initialSetup)
+
+ if (newLocale === 'en') {
+ return 'fr'
+ }
+ })
+
+ nuxtApp.hook('i18n:localeSwitched', ({ oldLocale, newLocale }) => {
+ console.log('onLanguageSwitched', oldLocale, newLocale)
+ })
+})

specs/callbacks.spec.ts → specs/runtime_hooks.spec.ts

@@ -8,23 +8,12 @@ await setup({
  browser: true,
  // overrides
  nuxtConfig: {
- i18n: {
- defaultLocale: 'en',
- // eslint-disable-next-line @typescript-eslint/no-explicit-any
- onBeforeLanguageSwitch: (oldLocale: string, newLocale: string, initialSetup: boolean, context: any) => {
- console.log('onBeforeLanguageSwitch', oldLocale, newLocale, initialSetup, context)
- if (newLocale === 'en') {
- return 'fr'
- }
- },
- onLanguageSwitched: (oldLocale: string, newLocale: string) => {
- console.log('onLanguageSwitched', oldLocale, newLocale)
- }
- }
+ plugins: [fileURLToPath(new URL(`./fixtures/plugins/i18nHooks.ts`, import.meta.url))],
+ i18n: { defaultLocale: 'en' }
  }
 })
 
-describe('onBeforeLanguageSwitch / onLanguageSwitched', () => {
+describe('beforeLocaleSwitch / localeSwitched', () => {
  test('<NuxtLink>', async () => {
  const home = url('/')
  const page = await createPage()

src/constants.ts

@@ -58,8 +58,6 @@ export const DEFAULT_OPTIONS = {
  customRoutes: 'page',
  pages: {},
  skipSettingLocaleOnNavigate: false,
- onBeforeLanguageSwitch: () => '',
- onLanguageSwitched: () => null,
  types: undefined,
  debug: false
 } as const

src/module.ts

@@ -277,6 +277,9 @@ function checkOptions(options: NuxtI18nOptions) {
  }
 }
 
+type MaybePromise<T> = T | Promise<T>
+type LocaleSwitch<T extends string = string> = { oldLocale: T; newLocale: T }
+
 declare module '@nuxt/schema' {
  interface NuxtConfig {
  i18n?: NuxtI18nOptions
@@ -286,3 +289,15 @@ declare module '@nuxt/schema' {
  'i18n:extend-messages': (messages: LocaleMessages<DefineLocaleMessage>[], localeCodes: string[]) => Promise<void>
  }
 }
+
+declare module '#app' {
+ interface RuntimeNuxtHooks {
+ 'i18n:beforeLocaleSwitch': <Context = unknown>(
+ params: LocaleSwitch & {
+ initialSetup: boolean
+ context: Context
+ }
+ ) => MaybePromise<void>
+ 'i18n:localeSwitched': (params: LocaleSwitch) => MaybePromise<void>
+ }
+}

src/options.d.ts

@@ -36,8 +36,5 @@ export {
  NuxtI18nOptionsDefault,
  NuxtI18nInternalOptions,
  DetectBrowserLanguageOptions,
- RootRedirectOptions,
- LanguageSwitchedHandler,
- BeforeLanguageSwitchHandler,
- LanguageSwitchedHandler
+ RootRedirectOptions
 } from './types'

src/runtime/plugins/i18n.ts

@@ -224,8 +224,12 @@ export default defineNuxtPlugin(async nuxt => {
  _getLocaleCookie(nuxt.ssrContext, { ...nuxtI18nOptions.detectBrowserLanguage, localeCodes })
  composer.setLocaleCookie = (locale: string) =>
  _setLocaleCookie(locale, nuxt.ssrContext, nuxtI18nOptions.detectBrowserLanguage || undefined)
- composer.onBeforeLanguageSwitch = nuxtI18nOptions.onBeforeLanguageSwitch
- composer.onLanguageSwitched = nuxtI18nOptions.onLanguageSwitched
+
+ composer.onBeforeLanguageSwitch = (oldLocale, newLocale, initialSetup, context) =>
+ nuxt.callHook('i18n:beforeLocaleSwitch', { oldLocale, newLocale, initialSetup, context })
+ composer.onLanguageSwitched = (oldLocale, newLocale) =>
+ nuxt.callHook('i18n:localeSwitched', { oldLocale, newLocale })
+
  composer.finalizePendingLocaleChange = async () => {
  if (!i18n.__pendingLocale) {
  return

src/runtime/types.d.ts

@@ -26,15 +26,15 @@ type BeforeLanguageSwitchHandler = (
  newLocale: string,
  initialSetup: boolean,
  context: NuxtApp
-) => string | void
+) => Promise<string | void>
 
 /**
  * Called after the app's locale is switched.
  *
  * @param oldLocale - The app's locale before the switch
  * @param newLocale - The app's locale after the switch.
  */
-type LanguageSwitchedHandler = (oldLocale: string, newLocale: string) => void
+type LanguageSwitchedHandler = (oldLocale: string, newLocale: string) => Promise<void>
 
 export interface ComposerCustomProperties {
  /**

src/runtime/utils.ts

@@ -171,7 +171,7 @@ export async function loadAndSetLocale<Context extends NuxtApp = NuxtApp>(
  }
 
  // call onBeforeLanguageSwitch
- const localeOverride = onBeforeLanguageSwitch(i18n, oldLocale, newLocale, initial, context)
+ const localeOverride = await onBeforeLanguageSwitch(i18n, oldLocale, newLocale, initial, context)
  const localeCodes = getLocaleCodes(i18n)
  if (localeOverride && localeCodes && localeCodes.includes(localeOverride)) {
  if (localeOverride === oldLocale) {
@@ -205,7 +205,7 @@ export async function loadAndSetLocale<Context extends NuxtApp = NuxtApp>(
  }
  setLocale(i18n, newLocale)
 
- onLanguageSwitched(i18n, oldLocale, newLocale)
+ await onLanguageSwitched(i18n, oldLocale, newLocale)
 
  ret = true
  return [ret, oldLocale]

src/types.ts

@@ -36,19 +36,8 @@ export type CustomRoutePages = {
  }
 }
 
-export type BeforeLanguageSwitchHandler = <Context = unknown>(
- oldLocale: string,
- newLocale: string,
- initialSetup: boolean,
- context: Context
-) => string | void
-
-export type LanguageSwitchedHandler = (oldLocale: string, newLocale: string) => void
-
 export type NuxtI18nOptions<Context = unknown> = {
  differentDomains?: boolean
- onBeforeLanguageSwitch?: BeforeLanguageSwitchHandler
- onLanguageSwitched?: LanguageSwitchedHandler
  detectBrowserLanguage?: DetectBrowserLanguageOptions | false
  langDir?: string | null
  lazy?: boolean | LazyOptions

test/__snapshots__/gen.test.ts.snap

@@ -24,7 +24,7 @@ export const resolveNuxtI18nOptions = async (context) => {
  return nuxtI18nOptions
 }
 
-export const nuxtI18nOptionsDefault = Object({vueI18n: undefined,locales: [],defaultLocale: \\"\\",defaultDirection: \\"ltr\\",routesNameSeparator: \\"___\\",trailingSlash: false,defaultLocaleRouteNameSuffix: \\"default\\",strategy: \\"prefix_except_default\\",lazy: false,langDir: null,rootRedirect: null,detectBrowserLanguage: Object({\\"alwaysRedirect\\":false,\\"cookieCrossOrigin\\":false,\\"cookieDomain\\":null,\\"cookieKey\\":\\"i18n_redirected\\",\\"cookieSecure\\":false,\\"fallbackLocale\\":\\"\\",\\"redirectOn\\":\\"root\\",\\"useCookie\\":true}),differentDomains: false,baseUrl: \\"\\",dynamicRouteParams: false,customRoutes: \\"page\\",pages: Object({}),skipSettingLocaleOnNavigate: false,onBeforeLanguageSwitch: (() => \\"\\"),onLanguageSwitched: (() => null),types: undefined,debug: false})
+export const nuxtI18nOptionsDefault = Object({vueI18n: undefined,locales: [],defaultLocale: \\"\\",defaultDirection: \\"ltr\\",routesNameSeparator: \\"___\\",trailingSlash: false,defaultLocaleRouteNameSuffix: \\"default\\",strategy: \\"prefix_except_default\\",lazy: false,langDir: null,rootRedirect: null,detectBrowserLanguage: Object({\\"alwaysRedirect\\":false,\\"cookieCrossOrigin\\":false,\\"cookieDomain\\":null,\\"cookieKey\\":\\"i18n_redirected\\",\\"cookieSecure\\":false,\\"fallbackLocale\\":\\"\\",\\"redirectOn\\":\\"root\\",\\"useCookie\\":true}),differentDomains: false,baseUrl: \\"\\",dynamicRouteParams: false,customRoutes: \\"page\\",pages: Object({}),skipSettingLocaleOnNavigate: false,types: undefined,debug: false})
 
 export const nuxtI18nInternalOptions = Object({__normalizedLocales: [Object({\\"code\\":\\"en\\"})]})
 export const NUXT_I18N_MODULE_ID = \\"@nuxtjs/i18n\\"
@@ -141,7 +141,7 @@ export const resolveNuxtI18nOptions = async (context) => {
  return nuxtI18nOptions
 }
 
-export const nuxtI18nOptionsDefault = Object({vueI18n: undefined,locales: [],defaultLocale: \\"\\",defaultDirection: \\"ltr\\",routesNameSeparator: \\"___\\",trailingSlash: false,defaultLocaleRouteNameSuffix: \\"default\\",strategy: \\"prefix_except_default\\",lazy: false,langDir: null,rootRedirect: null,detectBrowserLanguage: Object({\\"alwaysRedirect\\":false,\\"cookieCrossOrigin\\":false,\\"cookieDomain\\":null,\\"cookieKey\\":\\"i18n_redirected\\",\\"cookieSecure\\":false,\\"fallbackLocale\\":\\"\\",\\"redirectOn\\":\\"root\\",\\"useCookie\\":true}),differentDomains: false,baseUrl: \\"\\",dynamicRouteParams: false,customRoutes: \\"page\\",pages: Object({}),skipSettingLocaleOnNavigate: false,onBeforeLanguageSwitch: (() => \\"\\"),onLanguageSwitched: (() => null),types: undefined,debug: false})
+export const nuxtI18nOptionsDefault = Object({vueI18n: undefined,locales: [],defaultLocale: \\"\\",defaultDirection: \\"ltr\\",routesNameSeparator: \\"___\\",trailingSlash: false,defaultLocaleRouteNameSuffix: \\"default\\",strategy: \\"prefix_except_default\\",lazy: false,langDir: null,rootRedirect: null,detectBrowserLanguage: Object({\\"alwaysRedirect\\":false,\\"cookieCrossOrigin\\":false,\\"cookieDomain\\":null,\\"cookieKey\\":\\"i18n_redirected\\",\\"cookieSecure\\":false,\\"fallbackLocale\\":\\"\\",\\"redirectOn\\":\\"root\\",\\"useCookie\\":true}),differentDomains: false,baseUrl: \\"\\",dynamicRouteParams: false,customRoutes: \\"page\\",pages: Object({}),skipSettingLocaleOnNavigate: false,types: undefined,debug: false})
 
 export const nuxtI18nInternalOptions = Object({__normalizedLocales: [Object({\\"code\\":\\"en\\"})]})
 export const NUXT_I18N_MODULE_ID = \\"@nuxtjs/i18n\\"
@@ -172,7 +172,7 @@ export const resolveNuxtI18nOptions = async (context) => {
  return nuxtI18nOptions
 }
 
-export const nuxtI18nOptionsDefault = Object({vueI18n: undefined,locales: [],defaultLocale: \\"\\",defaultDirection: \\"ltr\\",routesNameSeparator: \\"___\\",trailingSlash: false,defaultLocaleRouteNameSuffix: \\"default\\",strategy: \\"prefix_except_default\\",lazy: false,langDir: null,rootRedirect: null,detectBrowserLanguage: Object({\\"alwaysRedirect\\":false,\\"cookieCrossOrigin\\":false,\\"cookieDomain\\":null,\\"cookieKey\\":\\"i18n_redirected\\",\\"cookieSecure\\":false,\\"fallbackLocale\\":\\"\\",\\"redirectOn\\":\\"root\\",\\"useCookie\\":true}),differentDomains: false,baseUrl: \\"\\",dynamicRouteParams: false,customRoutes: \\"page\\",pages: Object({}),skipSettingLocaleOnNavigate: false,onBeforeLanguageSwitch: (() => \\"\\"),onLanguageSwitched: (() => null),types: undefined,debug: false})
+export const nuxtI18nOptionsDefault = Object({vueI18n: undefined,locales: [],defaultLocale: \\"\\",defaultDirection: \\"ltr\\",routesNameSeparator: \\"___\\",trailingSlash: false,defaultLocaleRouteNameSuffix: \\"default\\",strategy: \\"prefix_except_default\\",lazy: false,langDir: null,rootRedirect: null,detectBrowserLanguage: Object({\\"alwaysRedirect\\":false,\\"cookieCrossOrigin\\":false,\\"cookieDomain\\":null,\\"cookieKey\\":\\"i18n_redirected\\",\\"cookieSecure\\":false,\\"fallbackLocale\\":\\"\\",\\"redirectOn\\":\\"root\\",\\"useCookie\\":true}),differentDomains: false,baseUrl: \\"\\",dynamicRouteParams: false,customRoutes: \\"page\\",pages: Object({}),skipSettingLocaleOnNavigate: false,types: undefined,debug: false})
 
 export const nuxtI18nInternalOptions = Object({__normalizedLocales: [Object({\\"code\\":\\"en\\"})]})
 export const NUXT_I18N_MODULE_ID = \\"@nuxtjs/i18n\\"