feat!: prepare for deprecation of i18n:extend-messages hook (#1969)

docs/content/2.guide/13.extend-messages.md

@@ -4,44 +4,12 @@ Nuxt hooks to extend i18n messages in your project.
 
 ---
 
-For **module authors** that want to provide messages with their modules, there are now two options to add or merge them into the normally loaded messages.
+If you're a **module author** and want that module to provide extra messages for your project, you can merge them into the normally loaded messages by using the `i18n:registerModule` hook.
 
 This is particularly useful if your module uses translated content and you want to offer nice default translations.
 
-1. [The `i18n:extend-messages` hook](#i18nextend-messages)
-2. [The `i18n:registerModule` hook](#i18nregistermodule)
-
-### `i18n:extend-messages`
-In your module's setup file listen to the Nuxt `i18n:extend-messages` hook and push your messages. `@nuxtjs/i18n` will do the rest.
-
-Example:
-
-```ts{}[my-module-example/module1.ts]
-import { defineNuxtModule } from '@nuxt/kit'
-
-export default defineNuxtModule({
-  setup(options, nuxt) {
-    nuxt.hook('i18n:extend-messages', async (additionalMessages, localeCodes) => {
-      additionalMessages.push({
-        en: {
-          'my-module-example': {
-            hello: 'Hello from external module'
-          }
-        },
-        fr: {
-          'my-module-example': {
-            hello: 'Bonjour depuis le module externe'
-          }
-        }
-      })
-    })
-  }
-})
-
-```
-
-### `i18n:registerModule`
-In your module's setup file listen to the Nuxt `i18n:registerModule` hook and register your i18n configuration, this is similar to how [lazy-load translations](./lazy-load-translations) are configured.
+In your module's setup file listen to the Nuxt `i18n:registerModule` hook and 
+register your i18n configuration, this is similar to how [lazy-load translations](./lazy-load-translations) are configured.
 
 Translations added this way will be loaded after those added in your project, and before extended layers.
 

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

@@ -145,6 +145,17 @@ Use `dynamicRouteParams` option. because, vuex no longer requires in Nuxt3.
 
 About details, See also [Lang Switcher](/api/lang-switcher#dynamic-route-parameters).
 
+### Deprecated `i18n:extend-messages` hook
+
+Use `i18n:registerModule` hook. because, there are two reasons for the below:
+
+- At build-time, the locale resources specified in the nuxt module are pre-compiled to javascript, and those resources are serialized into the runtime context with the nuxt template, which is unsafe.
+- For huge locale messages, performance will be slow down.
+
+Alternative `i18n:registerModule` hook works the same way like lazy loading translation as well. only the file information of the locale messages is serialized and passed to the runtime context. The locale messages loaded by dynaic import are then lazy-load, with no negative affect on performance.
+
+About details, see the [Extending messages hook](/guide/extend-messages).
+
 ### Deprecated `vueI18nLoader` option
 
 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**.

docs/content/4.API/5.nuxt.md

@@ -40,41 +40,6 @@ See more info about those in [Extension of Vue](/api/vue) section.
 
 ## Extension of NuxtHooks
 
-### `i18n:extend-messages` Hook
-
-- **Arguments**:
-  - additionalMessages (type: ` LocaleMessages<DefineLocaleMessage>[]`)
-  - localeCodes (type: `string[]`) - locale codes, which is resolved with `locales` option
-
-The `additionalMessages` array can be pushed locale messages paired with the locale.
-
-Example:
-
-```ts
-import { defineNuxtModule } from '@nuxt/kit'
-
-export default defineNuxtModule({
-  async setup(options, nuxt) {
-    nuxt.hook('i18n:extend-messages', (additionalMessages, localeCodes) => {
-      additionalMessages.push({
-        en: {
-          'my-module-exemple': {
-            hello: 'Hello from external module'
-          }
-        },
-        fr: {
-          'my-module-exemple': {
-            hello: 'Bonjour depuis le module externe'
-          }
-        }
-      })
-    })
-  }
-}
-```
-
-See also [Extending messages hook](/guide/extend-messages#i18nextend-messages)
-
 ### `i18n:registerModule` Hook
 
 - **Arguments**:
@@ -107,4 +72,4 @@ export default defineNuxtModule({
 })
 ```
 
-See also [Extending messages hook](/guide/extend-messages#i18nregistermodule)
+See also [Extending messages hook](/guide/extend-messages)

src/gen.ts

@@ -20,7 +20,7 @@ import { asVirtualId } from './transform/utils'
 
 import type { NuxtI18nOptions, NuxtI18nInternalOptions, LocaleInfo } from './types'
 import type { NuxtI18nOptionsDefault } from './constants'
-import type { AdditionalMessages } from './messages'
+import type { AdditionalMessages } from './messages' // TODO: remove `i18n:extend-messages` before v8 official release
 import type { File } from '@babel/types'
 
 export type LoaderOptions = {
@@ -29,7 +29,7 @@ export type LoaderOptions = {
   nuxtI18nOptions?: NuxtI18nOptions
   nuxtI18nOptionsDefault?: NuxtI18nOptionsDefault
   nuxtI18nInternalOptions?: NuxtI18nInternalOptions
-  additionalMessages?: AdditionalMessages
+  additionalMessages?: AdditionalMessages // TODO: remove `i18n:extend-messages` before v8 official release
 }
 
 const debug = createDebug('@nuxtjs/i18n:gen')
@@ -190,6 +190,7 @@ export function generateLoaderOptions(
       codes += `}\n`
       return codes
     } else if (rootKey === 'additionalMessages') {
+      // TODO: remove `i18n:extend-messages` before v8 official release
       return `export const ${rootKey} = ${generateAdditionalMessages(rootValue, misc.dev)}\n`
 	  } else {
 	    return `export const ${rootKey} = ${toCode(rootValue)}\n`
@@ -319,6 +320,7 @@ function generateVueI18nOptions(options: Record<string, any>, dev: boolean): str
   return genCode
 }
 
+// TODO: remove `i18n:extend-messages` before v8 official release
 function generateAdditionalMessages(value: Record<string, any>, dev: boolean): string {
   let genCode = 'Object({'
   for (const [locale, messages] of Object.entries(value)) {

src/module.ts

@@ -144,6 +144,12 @@ export default defineNuxtModule<NuxtI18nOptions>({
      * extend messages via 3rd party nuxt modules
      */
 
+    // TODO: remove `i18n:extend-messages` before v8 official release
+    logger.warn(
+      formatMessage(
+        "`i18n:extend-messages` is deprecated. That hook will be removed feature at the time of the v8 official release. If you're using it, please use `i18n:extend-messages` instead."
+      )
+    )
     const additionalMessages = await extendMessages(nuxt, localeCodes, options)
 
     /**
@@ -399,6 +405,7 @@ declare module '@nuxt/schema' {
   }
 
   interface NuxtHooks {
+    // TODO: remove `i18n:extend-messages` before v8 official release
     'i18n:extend-messages': (messages: LocaleMessages<DefineLocaleMessage>[], localeCodes: string[]) => Promise<void>
     'i18n:registerModule': (registerModule: (config: Pick<NuxtI18nOptions, 'langDir' | 'locales'>) => void) => void
   }

src/runtime/internal.ts

@@ -186,8 +186,10 @@ export async function loadLocale(
   }
 }
 
+// TODO: remove `i18n:extend-messages` before v8 official release
 const loadedAdditionalLocales: Locale[] = []
 
+// TODO: remove `i18n:extend-messages` before v8 official release
 export async function loadAdditionalLocale(
   context: NuxtApp,
   locale: Locale,

src/runtime/plugins/i18n.ts

@@ -18,7 +18,7 @@ import { localeCodes, resolveNuxtI18nOptions, nuxtI18nInternalOptions, isSSG, is
 import {
   loadInitialMessages,
   loadAndSetLocale,
-  mergeAdditionalMessages,
+  mergeAdditionalMessages, // TODO: remove `i18n:extend-messages` before v8 official release
   detectLocale,
   detectRedirect,
   navigate,
@@ -395,6 +395,7 @@ export default defineNuxtPlugin(async nuxt => {
   // inject for nuxt helpers
   inejctNuxtHelpers(nuxtContext, i18n)
 
+  // TODO: remove `i18n:extend-messages` before v8 official release
   // merge addtional locale messages
   await mergeAdditionalMessages(nuxtContext, i18n, initialLocale)
 

src/runtime/utils.ts

@@ -25,7 +25,7 @@ import {
   callVueI18nInterfaces,
   getVueI18nPropertyValue,
   loadLocale,
-  loadAdditionalLocale,
+  loadAdditionalLocale, // TODO: remove `i18n:extend-messages` before v8 official release
   defineGetter,
   getLocaleDomain,
   getDomainFromLocale,
@@ -60,6 +60,7 @@ export function setLocaleMessage(i18n: I18n, locale: Locale, messages: Record<st
   return callVueI18nInterfaces(i18n, 'setLocaleMessage', locale, messages)
 }
 
+// TODO: remove `i18n:extend-messages` before v8 official release
 export function mergeLocaleMessage(i18n: I18n, locale: Locale, messages: Record<string, any>) {
   return callVueI18nInterfaces(i18n, 'mergeLocaleMessage', locale, messages)
 }
@@ -128,6 +129,7 @@ export async function loadInitialMessages<Context extends NuxtApp = NuxtApp>(
   return messages
 }
 
+// TODO: remove `i18n:extend-messages` before v8 official release
 export async function mergeAdditionalMessages<Context extends NuxtApp = NuxtApp>(
   context: Context,
   i18n: I18n,