refactor!: vueI18n options from config path (#1973)

* docs: mention callbacks * chore: initial commit * chore: progress * chore: updating minor bits and tests * refactor!: `vueI18n` options from config path * fix: complete config load implementation * updates * fix: unit tests * fix: e2e testing * update lock file * tweak docs --------- Co-authored-by: Inesh Bose <2504266b@student.gla.ac.uk>
nuxt-modules · Apr 12, 2023 · f7925d1 · f7925d1
1 parent dd40bfe
commit f7925d1
Show file tree

Hide file tree

Showing 98 changed files with 1,645 additions and 705 deletions.
diff --git a/docs/content/1.getting-started/2.basic-usage.md b/docs/content/1.getting-started/2.basic-usage.md
@@ -8,34 +8,37 @@ The basics to get started with the Nuxt i18n module is to translate with Vue I18
 
 The basic to get started with **Nuxt i18n module** is to **translate with Vue I18n via the `vueI18n` option**
 
-So, let's get started configuring the following `nuxt.config`:
+So, let's get started by adding the module to `nuxt.config`:
 
 ```ts {}[nuxt.config.ts]
 export default defineNuxtConfig({
   modules: [
     '@nuxtjs/i18n'
   ],
   i18n: {
-    // add `vueI18n` option to `@nuxtjs/i18n` module options
-    vueI18n: {
-      legacy: false,
-      locale: 'en',
-      messages: {
-        en: {
-          welcome: 'Welcome'
-        },
-        fr: {
-          welcome: 'Bienvenue'
-        }
-      }
-    }
+    vueI18n: './i18n.config.ts' // if you are using custom path, default 
   }
 })
 ```
 
-The `vueI18n` option is the same as `createI18n` function option of Vue I18n. `vueI18n` option is passed to the `createI18n` function via the nuxt plugin of this module internally.
+```ts {}[i18n.config.ts]
+export default defineI18nConfig(nuxt => ({
+  legacy: false,
+  locale: 'en',
+  messages: {
+    en: {
+      welcome: 'Welcome'
+    },
+    fr: {
+      welcome: 'Bienvenue'
+    }
+  }
+}))
+```
+
+The `i18n.config` file exports the same options as `createI18n` function of Vue I18n. The configuration is passed to the `createI18n` function via the nuxt plugin (runtime) of this module internally.
 
-For more details about the `vueI18n` option, see the [Vue I18n documentation](https://vue-i18n.intlify.dev/api/general.html#createi18n).
+For more details about configuration, see the [Vue I18n documentation](https://vue-i18n.intlify.dev/api/general.html#createi18n).
 
 Now, put (or edit) the following the page component in `pages` directory of you project:
 
@@ -103,18 +106,6 @@ For localizing links, you can use the code provided from the `locales` option as
    i18n: {
 +    locales: ['en', 'fr'],  // used in URL path prefix
 +    defaultLocale: 'en',    // default locale of your project for Nuxt pages and routings
-     vueI18n: {
-       legacy: false,
-       locale: 'en',
-       messages: {
-         en: {
-           welcome: 'Welcome'
-         },
-         fr: {
-           welcome: 'Bienvenue'
-         }
-       }
-     }
    }
  })
 ```

diff --git a/docs/content/2.guide/11.locale-fallback.md b/docs/content/2.guide/11.locale-fallback.md
@@ -7,29 +7,22 @@ How a fallback gets selected when a translation is missing.
 **Nuxt i18n module** takes advantage of **Vue I18n** ability to handle localization fallback. It is possible to define a single fallback locale, an array of locales,
 or a decision map for more specific needs.
 
-```js [nuxt.config.js]
-export default defineNuxtConfig({
+```js [i18n.config.ts]
+export default {
+  fallbackLocale: 'en',
+  // or
+  fallbackLocale: ['en', 'fr'],
+  // or
+  fallbackLocale: {
+    'de-CH':   ['fr', 'it'],
+    'zh-Hant': ['zh-Hans'],
+    'es-CL':   ['es-AR'],
+    'es':      ['en-GB'],
+    'pt':      ['es-AR'],
+    'default': ['en', 'da']
+  }
   // ...
-
-  i18n: {
-    vueI18n: {
-      fallbackLocale: 'en',
-      // or
-      fallbackLocale: ['en', 'fr'],
-      // or
-      fallbackLocale: {
-        'de-CH':   ['fr', 'it'],
-        'zh-Hant': ['zh-Hans'],
-        'es-CL':   ['es-AR'],
-        'es':      ['en-GB'],
-        'pt':      ['es-AR'],
-        'default': ['en', 'da']
-      }
-    }
-  },
-
-  // ...
-})
+}
 ```
 
 More information in [Vue I18n documentation](https://vue-i18n.intlify.dev/guide/essentials/fallback.html)
diff --git a/docs/content/2.guide/16.migrating.md b/docs/content/2.guide/16.migrating.md
@@ -4,8 +4,20 @@ Follow this guide to upgrade from one major version to the other.
 
 ---
 
+::alert{type="warning"}
+Here, deprecated = removed
+::
+
 ## Upgrading from `nuxtjs/i18n` v7.x
 
+### Deprecated `vueI18n` option to not accept `createI18n` options
+
+This is to ensure stability and distinction between compile / build-time and runtime since vue-i18n is used in runtime.
+
+See more about detail, please [GitHub Pull request](https://github.com/nuxt-modules/i18n/pull/1948#issuecomment-1482749302)
+
+You can continue defining `vueI18n` options in `i18n.config`. Refer to [Vue i18n](/options/vue-i18n) section and [basic usage](/getting-started/basic-usage/#translate-with-vue-i18n) for an example.
+
 ### Change the route key rules in `pages` option
 
 The key of route set in the `pages` option has been changed to be file-based relative to the `pages/` directory in Nuxt, and **excluding the leading `/`**. 

diff --git a/docs/content/2.guide/8.lazy-load-translations.md b/docs/content/2.guide/8.lazy-load-translations.md
@@ -164,10 +164,6 @@ export default defineNuxtConfig({
     lazy: true,
     langDir: 'lang',
     defaultLocale: 'en',
-    vueI18n: {
-      // If fallback is needed, you need to define
-      fallbackLocale: 'en',
-    }
   },
 
   // ...

diff --git a/docs/content/3.options/1.vue-i18n.md b/docs/content/3.options/1.vue-i18n.md
@@ -6,34 +6,67 @@ Related Vue I18n options.
 
 ## `vueI18n`
 
-- type: `object` or `string`
-- default: `{}`
+- type: `string`
+- default: `''`
 
-Configuration for the `vue-i18n` library that is used internally by this module. See full documentation at https://vue-i18n.intlify.dev/api/general.html#createi18n
+Build-time configuration for Vue I18n options that is used internally by this module. See full documentation at https://vue-i18n.intlify.dev/api/general.html#createi18n
 
-::alert{type="info"}
+Configuration for `createI18n` can be passed using a configuration file. By default, the module will scan for a `i18n.config{.js,.mjs,.ts}` if nothing is specified.
 
-It's also supported to set this property to a path to a local configuration file. The file needs to export a function or plain object. If a function, it will be passed a Nuxt Context as a parameter. It's necessary to use that approach when overriding more complex types (like functions) that can't be stringified correctly.
 
-```ts {}[~/vue-i18n.options.ts]
-import type { I18nOptions } from 'vue-i18n'
-import type { NuxtApp } from 'nuxt/dist/app/index'
+```ts {}[nuxt.config.ts]
+export default defineNuxtConfig({
+  modules: [
+    '@nuxtjs/i18n'
+  ],
+  i18n: {
+    vueI18n: './nuxt-i18n.js' // custom path example
+  }
+})
+```
 
-export default function (nuxt: NuxtApp) {
-  return {
-    modifiers: {
-      snakeCase: (str) => str.split(' ').join('-')
+You need to `export default` with **plain object** or **function**.
+
+export with plain object example:
+
+```ts
+export default {
+  legacy: false,
+  locale: 'en',
+  messages: {
+    en: {
+      welcome: 'Welcome'
+    },
+    fr: {
+      welcome: 'Bienvenue'
     }
-  } as I18nOptions
+  }
 }
 ```
 
-::
+export with fucntion example:
+
+```ts
+import en from '../locales/en.json'
+import fr from '../locales/fr.yaml'
+
+// You can use `defineI18nConfig` to get type inferences for options to pass to vue-i18n.
+export default defineI18nConfig(nuxt => {
+  return {
+    legacy: false,
+    locale: 'en',
+    messages: {
+      en,
+      fr
+    }
+  }
+})
+```
 
 ::alert{type="warning"}
 
-The `messages` option cannot be included in an object and exported with function due to limitations in Vue I18n v9 handling of locale messages.
+The Vue I18n `messages` option should be returned **by the plain object**. 
 
-As the workaround, you can use [lazy-load transtions](/guide/lazy-load-translations) in Nuxt i18n module. locale messages handled with lazy-load transtions will be loaded as locale messges inside Vue i18n.
+That will be pre-compiled in the nuxt i18n module via vue-i18n message-compiler as an executable message in the vue-i18n runtime.
 
 ::
diff --git a/docs/content/3.options/6.misc.md b/docs/content/3.options/6.misc.md
@@ -47,8 +47,8 @@ Supported properties:
 
 ## `types`
 
-- type: `string` (`composition` or `legacy`) | `undefined`
-- default: `undefined`
+- type: `string` (`composition` or `legacy`)
+- default: `composition`
 
 Enforces the type definition of the API style to be used. if you set `compostion`, Composition API types provided by Vue I18n and `@nuxtjs/i18n` are supported, else  `legacy`, Options API types are supported. If you are running a dev server with `nuxi dev`, watching the Nuxt configuration will switch the type. 
 

diff --git a/docs/content/4.API/1.composables.md b/docs/content/4.API/1.composables.md
@@ -177,6 +177,51 @@ Note that if the value of `detectBrowserLanguage.useCookie` is `false`, an **emp
 declare function useCookieLocale(): Ref<string>;
 ```
 
+## `defineI18nConfig`
+
+The `defineI18nConfig` defines a composable function to vue-i18n configuration.
+
+This function is used to pass the `createI18n` options on nuxt i18n module.
+
+For more details about configuration, see the [Vue I18n documentation](https://vue-i18n.intlify.dev/api/general.html#createi18n).
+
+You need return vue-i18n options object that will be resolved by Promise.
+
+### Type
+
+```ts
+export function defineI18nConfig<Config extends I18nOptions>(loader: (context: NuxtApp) => Config | Promise<Config>): (context: NuxtApp) => Config | Promise<Config>;
+```
+
+for example, define simple vue-i18n options object:
+```ts
+export default defineI18nConfig(nuxt => ({
+  legacy: false,
+  locale: 'en',
+  messages: {
+    en: {
+      welcome: 'Welcome'
+    },
+    fr: {
+      welcome: 'Bienvenue'
+    }
+  }
+}))
+```
+
+### Parameters
+
+#### `loader`
+
+A function that is the vue-i18n optionss loading, that has the following parameters:
+
+- `context`
+
+  **Type**: `NuxtApp`
+
+  A Nuxt Application instance that is passed from nuxt i18n module.
+
+
 ## `defineI18nLocale`
 
 The `defineI18nLocale` defines a composable function to dynamically load locale messages.

diff --git a/playground/i18n.config.ts b/playground/i18n.config.ts
@@ -0,0 +1,22 @@
+import type { I18nOptions } from 'vue-i18n'
+
+export default {
+  legacy: false,
+  locale: 'en',
+  fallbackLocale: 'fr',
+  modifiers: {
+    snakeCase: (str: string) => str.split(' ').join('-')
+  },
+  messages: {
+    ja: {
+      bar: {
+        buz: 'バズ'
+      }
+    }
+  }
+  // fallbackLocale: {
+  //   en: ['ja', 'fr', 'en-US'],
+  //   ja: ['en', 'fr', 'ja-JP'],
+  //   fr: ['en', 'ja', 'fr-FR']
+  // }
+} as I18nOptions
diff --git a/playground/layer-module/locales/en.json b/playground/layer-module/locales/en.json
@@ -1,3 +1,3 @@
 {
-	"moduleLayerText": "This is a merged module layer locale key"
-}
+  "moduleLayerText": "This is a merged module layer locale key"
+}
diff --git a/playground/layer-module/locales/fr.json b/playground/layer-module/locales/fr.json
@@ -1,3 +1,3 @@
 {
-	"moduleLayerText": "This is a merged module layer locale key in French"
-}
+  "moduleLayerText": "This is a merged module layer locale key in French"
+}
diff --git a/playground/layer-module/locales/nl.json b/playground/layer-module/locales/nl.json
@@ -1,3 +1,3 @@
 {
-	"moduleLayerText": "This is a merged module layer locale key in Dutch"
-}
+  "moduleLayerText": "This is a merged module layer locale key in Dutch"
+}
diff --git a/playground/layers/i18n-layer/i18n.config.ts b/playground/layers/i18n-layer/i18n.config.ts
@@ -0,0 +1,9 @@
+export default defineI18nConfig(() => {
+  return {
+    messages: {
+      ja: {
+        layerText: 'これはマージされたロケールキーです'
+      }
+    }
+  }
+})
diff --git a/playground/layers/i18n-layer/locales/en.json b/playground/layers/i18n-layer/locales/en.json
@@ -1,3 +1,3 @@
 {
-	"layerText": "This is a merged locale key"
-}
+  "layerText": "This is a merged locale key"
+}
diff --git a/playground/layers/i18n-layer/locales/fr.json b/playground/layers/i18n-layer/locales/fr.json
@@ -1,3 +1,3 @@
 {
-	"layerText": "This is a merged locale key in French"
-}
+  "layerText": "This is a merged locale key in French"
+}
diff --git a/playground/layers/i18n-layer/locales/nl.json b/playground/layers/i18n-layer/locales/nl.json
@@ -1,3 +1,3 @@
 {
-	"layerText": "This is a merged locale key in Dutch"
-}
+  "layerText": "This is a merged locale key in Dutch"
+}
diff --git a/playground/locales/en-KK.js b/playground/locales/en-KK.js
@@ -0,0 +1,5 @@
+export default {
+  bar: {
+    buz: 'Hello, {name}!'
+  }
+}