From 2c39470862d16af78006818b7b7eab74f7a26290 Mon Sep 17 00:00:00 2001 From: kazuya kawaguchi Date: Fri, 31 Mar 2023 02:42:12 +0900 Subject: [PATCH] feat!: prepare for deprecation of `i18n:extend-messages` hook (#1969) --- docs/content/2.guide/13.extend-messages.md | 38 ++-------------------- docs/content/2.guide/16.migrating.md | 11 +++++++ docs/content/4.API/5.nuxt.md | 37 +-------------------- src/gen.ts | 6 ++-- src/module.ts | 7 ++++ src/runtime/internal.ts | 2 ++ src/runtime/plugins/i18n.ts | 3 +- src/runtime/utils.ts | 4 ++- 8 files changed, 33 insertions(+), 75 deletions(-) diff --git a/docs/content/2.guide/13.extend-messages.md b/docs/content/2.guide/13.extend-messages.md index 3f436d209..3596ac628 100644 --- a/docs/content/2.guide/13.extend-messages.md +++ b/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. diff --git a/docs/content/2.guide/16.migrating.md b/docs/content/2.guide/16.migrating.md index c7d3cc40a..3a86c42b0 100644 --- a/docs/content/2.guide/16.migrating.md +++ b/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**. diff --git a/docs/content/4.API/5.nuxt.md b/docs/content/4.API/5.nuxt.md index 4b79181c5..b6bc61dae 100644 --- a/docs/content/4.API/5.nuxt.md +++ b/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[]`) - - 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) diff --git a/src/gen.ts b/src/gen.ts index cf641ce58..9c8d9ad62 100644 --- a/src/gen.ts +++ b/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, dev: boolean): str return genCode } +// TODO: remove `i18n:extend-messages` before v8 official release function generateAdditionalMessages(value: Record, dev: boolean): string { let genCode = 'Object({' for (const [locale, messages] of Object.entries(value)) { diff --git a/src/module.ts b/src/module.ts index 6ec0e70d6..e1741c9fb 100644 --- a/src/module.ts +++ b/src/module.ts @@ -144,6 +144,12 @@ export default defineNuxtModule({ * 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[], localeCodes: string[]) => Promise 'i18n:registerModule': (registerModule: (config: Pick) => void) => void } diff --git a/src/runtime/internal.ts b/src/runtime/internal.ts index a2df68f6d..55956185c 100644 --- a/src/runtime/internal.ts +++ b/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, diff --git a/src/runtime/plugins/i18n.ts b/src/runtime/plugins/i18n.ts index 548dc0060..fa91a16db 100644 --- a/src/runtime/plugins/i18n.ts +++ b/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) diff --git a/src/runtime/utils.ts b/src/runtime/utils.ts index 78f69af8a..9dd150b88 100644 --- a/src/runtime/utils.ts +++ b/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) { return callVueI18nInterfaces(i18n, 'mergeLocaleMessage', locale, messages) } @@ -128,6 +129,7 @@ export async function loadInitialMessages( return messages } +// TODO: remove `i18n:extend-messages` before v8 official release export async function mergeAdditionalMessages( context: Context, i18n: I18n,