fix: options passed with installModule are overwritten (#2882)

* fix: locales provided via `installModule` being ignored

* fix: use `locales` and `vueI18n` passed by `installModule`

* test: add `installModule` options tests

* docs: add `installModule` documentation

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

@@ -15,7 +15,7 @@ Translations added this way will be loaded after those added in your project, an
 Example:
 ::code-group
 
-```ts[my-module-example/module.ts]
+```ts [my-module-example/module.ts]
 import { createResolver, defineNuxtModule } from '@nuxt/kit'
 
 export default defineNuxtModule({

docs/content/docs/2.guide/14.layers.md

@@ -1,6 +1,6 @@
 ---
-title: Layers pages
-description: How Nuxt i18n handles layers.
+title: Layers
+description: Using layers to extends projects with Nuxt i18n.
 ---
 
 Nuxt i18n module supports layers and will automatically combine i18n configuration of all extended layers. [Read more about layers here](https://nuxt.com/docs/getting-started/layers)

docs/content/docs/2.guide/16.install-module.md

@@ -0,0 +1,66 @@
+---
+title: Installing from a module
+description: How to install Nuxt i18n using `installModule` inside of a module.
+---
+
+If you're a **module author** and want your module to install Nuxt i18n, you can do so using `installModule` but you will have to resolve paths used for `vueI18n`, `langDir` and those configured in `locales`.
+
+::callout
+We strongly recommend using [layers](/docs/guide/layers) for complete module installations over using `installModule`, layers are merged by priority which allows projects to overwrite options as desired and will not cause conflicts if more than one layer provides options for the Nuxt i18n module.
+
+:br :br
+
+If you would only like your module to provide translations, consider using the hook described in [extend-messages](/docs/guide/extend-messages) instead.
+::
+
+Note that when using `installModule`, the options passed will essentially have a higher priority than any layer (including the project layer), options are merged when possible and applicable but will otherwise override configurations.
+
+Example:
+::code-group
+
+```ts [my-module-example/module.ts]
+import { createResolver, defineNuxtModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  async setup(options, nuxt) {
+    const { resolve } = createResolver(import.meta.url)
+
+    // paths needs to be resolved so absolute paths are used
+    await installModule('@nuxtjs/i18n', {
+      vueI18n: resolve('./i18n.config.ts'),
+      langDir: resolve('./lang'),
+      locales: [
+        {
+          code: 'en',
+          file: resolve('./lang/en.json'),
+        },
+        {
+          code: 'fr',
+          file: resolve('./lang/fr.json'),
+        },
+      ]
+    })
+  }
+})
+```
+
+```json [lang/en.json]
+{
+  "my-module-example": {
+    "hello": "Hello from external module"
+  }
+}
+```
+
+```json [lang/fr.json]
+{
+  "my-module-example": {
+    "hello": "Bonjour depuis le module externe"
+  }
+}
+```
+
+::
+
+Now the project has access to new messages and can use them through `$t('my-module-example.hello')`.
+

specs/basic_usage.spec.ts

@@ -617,4 +617,11 @@ describe('basic usage', async () => {
     expect(dom.querySelector('head #switch-locale-path').content).toEqual('/fr/composables')
     expect(dom.querySelector('head #route-base-name').content).toEqual('nested-test-route')
   })
+
+  test('(#2874) options `locales` and `vueI18n` passed using `installModule` are not overridden', async () => {
+    const { page } = await renderPage('/')
+
+    expect(await getText(page, '#install-module-locale')).toEqual('Installer module locale works!')
+    expect(await getText(page, '#install-module-vue-i18n')).toEqual('Installer module vue-i18n works!')
+  })
 })

specs/fixtures/basic_usage/installer-module/i18n.config.ts

@@ -0,0 +1,9 @@
+import type { I18nOptions } from 'vue-i18n'
+
+export default {
+  messages: {
+    en: {
+      installerModuleVueI18nMessage: 'Installer module vue-i18n works!'
+    }
+  }
+} as I18nOptions

specs/fixtures/basic_usage/installer-module/index.ts

@@ -0,0 +1,20 @@
+import { createResolver, defineNuxtModule, installModule } from '@nuxt/kit'
+
+export default defineNuxtModule({
+  async setup(options, nuxt) {
+    const { resolve } = createResolver(import.meta.url)
+
+    installModule('@nuxtjs/i18n', {
+      langDir: resolve('./locales'),
+      vueI18n: resolve('./i18n.config.ts'),
+      locales: [
+        {
+          code: 'en',
+          iso: 'en',
+          files: [resolve('./locales/en.json')],
+          name: 'English'
+        }
+      ]
+    })
+  }
+})

specs/fixtures/basic_usage/installer-module/locales/en.json

@@ -0,0 +1,3 @@
+{
+  "installerModuleLocaleMessage": "Installer module locale works!"
+}

specs/fixtures/basic_usage/nuxt.config.ts

@@ -1,7 +1,7 @@
 // https://nuxt.com/docs/guide/directory-structure/nuxt.config
 export default defineNuxtConfig({
   devtools: { enabled: true },
-  modules: ['./layer-module', '@nuxtjs/i18n'],
+  modules: ['./layer-module', './installer-module', '@nuxtjs/i18n'],
   runtimeConfig: {
     public: {
       runtimeValue: 'Hello from runtime config!',

specs/fixtures/basic_usage/pages/index.vue

@@ -239,5 +239,9 @@ useHead({
       <code id="global-scope-properties">{{ localeProperties }}</code>
       <LocalScope />
     </section>
+    <section>
+      <div id="install-module-locale">{{ $t('installerModuleLocaleMessage') }}</div>
+      <div id="install-module-vue-i18n">{{ $t('installerModuleVueI18nMessage') }}</div>
+    </section>
   </div>
 </template>

src/layers.ts

@@ -1,14 +1,21 @@
 import createDebug from 'debug'
-import { getLayerI18n, getProjectPath, mergeConfigLocales, resolveVueI18nConfigInfo, formatMessage } from './utils'
+import {
+  getLayerI18n,
+  getProjectPath,
+  mergeConfigLocales,
+  resolveVueI18nConfigInfo,
+  formatMessage,
+  getLocaleFiles
+} from './utils'
 
 import { useLogger } from '@nuxt/kit'
-import { isAbsolute, resolve } from 'pathe'
+import { isAbsolute, parse, resolve } from 'pathe'
 import { isString } from '@intlify/shared'
 import { NUXT_I18N_MODULE_ID } from './constants'
 
 import type { LocaleConfig } from './utils'
 import type { Nuxt, NuxtConfigLayer } from '@nuxt/schema'
-import type { NuxtI18nOptions, VueI18nConfigPathInfo } from './types'
+import type { LocaleObject, NuxtI18nOptions, VueI18nConfigPathInfo } from './types'
 
 const debug = createDebug('@nuxtjs/i18n:layers')
 
@@ -60,6 +67,11 @@ export const checkLayerOptions = (options: NuxtI18nOptions, nuxt: Nuxt) => {
   }
 }
 
+/**
+ * Merges `locales` configured by each layer and resolves the locale `files` to absolute paths.
+ *
+ * This overwrites `options.locales`
+ */
 export const applyLayerOptions = (options: NuxtI18nOptions, nuxt: Nuxt) => {
   const project = nuxt.options._layers[0]
   const layers = nuxt.options._layers
@@ -107,6 +119,43 @@ export const mergeLayerLocales = (options: NuxtI18nOptions, nuxt: Nuxt) => {
       }
     })
 
+  const localeObjects = options.locales.filter((x): x is LocaleObject => x !== 'string')
+  const absoluteConfigMap = new Map<string, LocaleConfig>()
+  // locale `files` use absolute paths installed using `installModule`
+  const absoluteLocaleObjects = localeObjects.filter(localeObject => {
+    const files = getLocaleFiles(localeObject)
+    if (files.length === 0) return false
+    return files.every(
+      file => isAbsolute(file.path) && configs.find(config => config.langDir === parse(file.path).dir) == null
+    )
+  })
+
+  // filter layer locales
+  for (const absoluteLocaleObject of absoluteLocaleObjects) {
+    const files = getLocaleFiles(absoluteLocaleObject)
+    if (files.length === 0) continue
+    const langDir = parse(files[0].path).dir
+
+    if (absoluteConfigMap.has(langDir)) {
+      const entry = absoluteConfigMap.get(langDir)
+
+      absoluteConfigMap.set(langDir, {
+        langDir,
+        projectLangDir,
+        locales: [...(entry!.locales! as LocaleObject[]), absoluteLocaleObject]
+      })
+      continue
+    }
+
+    absoluteConfigMap.set(langDir, {
+      langDir,
+      projectLangDir,
+      locales: [absoluteLocaleObject]
+    })
+  }
+
+  configs.unshift(...Array.from(absoluteConfigMap.values()))
+
   return mergeConfigLocales(configs)
 }
 
@@ -126,7 +175,7 @@ export const getLayerLangPaths = (nuxt: Nuxt) => {
     }) as string[]
 }
 
-export async function resolveLayerVueI18nConfigInfo(nuxt: Nuxt, buildDir: string) {
+export async function resolveLayerVueI18nConfigInfo(options: NuxtI18nOptions, nuxt: Nuxt, buildDir: string) {
   const logger = useLogger(NUXT_I18N_MODULE_ID)
   const layers = [...nuxt.options._layers]
   const project = layers.shift() as NuxtConfigLayer
@@ -158,5 +207,10 @@ export async function resolveLayerVueI18nConfigInfo(nuxt: Nuxt, buildDir: string
       })
   )
 
+  // use `vueI18n` passed by `installModule`
+  if (options.vueI18n && isAbsolute(options.vueI18n)) {
+    resolved.unshift(await resolveVueI18nConfigInfo({ vueI18n: options.vueI18n }, buildDir, parse(options.vueI18n).dir))
+  }
+
   return resolved.filter((x): x is Required<VueI18nConfigPathInfo> => x != null)
 }

src/module.ts

@@ -186,7 +186,7 @@ export default defineNuxtModule<NuxtI18nOptions>({
      * resolve vue-i18n config path
      */
 
-    const vueI18nConfigPaths = await resolveLayerVueI18nConfigInfo(nuxt, nuxt.options.buildDir)
+    const vueI18nConfigPaths = await resolveLayerVueI18nConfigInfo(options, nuxt, nuxt.options.buildDir)
     debug('VueI18nConfigPaths', vueI18nConfigPaths)
 
     /**