feat: configurable directory restructure (#3054)

* feat: i18n dir resolve

* feat: i18n dir resolve

* test: add restructure test

* refactor: file resolution

* fix: layer option validation

* docs: describe breaking folder structure change

* fix: layer validation

* chore: update lockfile

* test: change fixture structure

* feat: `restructureDir` option

* docs: describe restructure and compatible option

docs/content/docs/3.options/10.misc.md

@@ -64,3 +64,14 @@ Don't enable this option in production. It's not optimized for it.
 - default: `false`
 
 Set the plugin as `parallel`. See [nuxt plugin loading strategy](https://nuxt.com/docs/guide/directory-structure/plugins#loading-strategy).
+
+## `restructureDir`
+
+- type: `string | undefined`
+- default: `undefined`
+
+Can be used to configure the directory used to resolve i18n files, this will be set to `i18n` by default in the v9 release.
+
+::callout{icon="i-heroicons-exclamation-triangle" color="amber"}
+Setting this value will also change the default value for `langDir`, which is `locales` if unset, this is the new default value in v9.
+::

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

@@ -37,7 +37,6 @@ export default defineNuxtConfig({
   modules: ['@nuxtjs/i18n'],
   i18n: {
     lazy: true,
-    langDir: './lang',
     locales: [
       { code: 'en', file: 'en.json' },
       { code: 'nl', file: 'nl.json' }
@@ -60,7 +59,6 @@ Locales provided by a project will be merged with those provided by extended lay
 export default defineNuxtConfig({
   extends: ['my-layer'],
   i18n: {
-    langDir: './lang',
     locales: [{ code: 'en', file: 'en.json' }]
   }
 })
@@ -71,7 +69,6 @@ export default defineNuxtConfig({
   modules: ['@nuxtjs/i18n'],
   i18n: {
     lazy: true,
-    langDir: './lang',
     locales: [
       { code: 'en', file: 'en.json' },
       { code: 'nl', file: 'nl.json' }
@@ -83,20 +80,20 @@ export default defineNuxtConfig({
 ::
 
 ::callout{icon="i-heroicons-light-bulb"}
-Note how some options such as `lazy` are inherited, while options such as `langDir` and `locales` need to be set for every layer (project included) providing locale files.
+Note how some options such as `lazy` are inherited, while options such as `locales` need to be set for every layer (project included) providing locale files.
 ::
 
 This example would result in the project supporting two locales (`en`, `nl`) and would add the additional messages added for the `en` locale.
 
 ::code-group
 
-```ts [project/lang/en.json]
+```ts [project/i18n/locales/en.json]
 {
   "title": "foo"
 }
 ```
 
-```ts [project/my-layer/lang/en.json]
+```ts [project/my-layer/i18n/locales/en.json]
 {
   "title": "layer title",
   "description": "bar"

docs/content/docs/5.v9/2.guide/15.server-side-translations.md

@@ -17,7 +17,7 @@ Nuxt i18n exports the `defineI18nLocaleDetector` composable function to define i
 
 The following is an example of how to define a detector that detects locale using query, cookie, and header:
 
-```ts [localeDetector.ts]
+```ts [i18n/localeDetector.ts]
 // Detect based on query, cookie, header
 export default defineI18nLocaleDetector((event, config) => {
   // try to get locale from query
@@ -53,7 +53,7 @@ The following is an example of a locale detector configuration defined directly
 export default defineNuxtConfig({
   i18n: {
     experimental: {
-      localeDetector: './localeDetector.ts'
+      localeDetector: 'localeDetector.ts'
     }
   }
 })

docs/content/docs/5.v9/2.guide/18.breaking-changes-in-v9.md

@@ -22,3 +22,28 @@ https://vue-i18n.intlify.dev/guide/migration/breaking10.html#default-enable-for-
 
 Accordingly, the `jit` option in Nuxt I18n v8 is no longer needed, so this option has been removed.
 
+## Directory restructure and `langDir` default value
+
+We now use a default directory structure that is consistent with [directory structure changes in Nuxt 4](https://nuxt.com/docs/getting-started/upgrade#new-directory-structure).
+
+What changed
+  * `langDir` now defaults to `locales`.
+  * All i18n files are resolved relative to `<rootDir>/i18n`, this can be configured with the `restructureDir` option.
+
+Here is an example of a project structure after this change:
+
+```sh
+app/
+server/
+i18n/
+  locales/
+    en.json
+    ja.json
+  i18n.config.ts
+  localeDetector.ts
+nuxt.config.ts
+```
+
+Reasons for change
+  1. Context - i18n files are used both server-side and client-side, using a dedicated `i18n/` folder in the root directory outside `app/` and `server/` makes more sense.
+  2. Clean - less clutter/fragmentation of i18n files, and should make resolving and loading files easier for us.

docs/content/docs/5.v9/2.guide/7.lazy-load-translations.md

@@ -8,7 +8,6 @@ This can be achieved with **Nuxt i18n module** by letting the module know where
 To enable translations lazy-loading, follow these steps when configuring **Nuxt i18n module**:
 
 - Set `lazy` option to `true` (or to [configuration object](/docs/options/lazy#lazy) if you want to customize some options).
-- Set `langDir` option to the directory (cannot be empty) that contains your translation files.
 - Configure `locales` option as an array of objects, where each object has a `file` or `files` key whose value is the translation file corresponding to the locale.
 - Optionally, remove all messages that you might have passed to Vue I18n via the `vueI18n` option.
 - Each `file` or `files` can return either an `Object`, or a function that returns `Promise` which must return an `Object`.
@@ -19,10 +18,11 @@ Example files structure:
 
 ```
 nuxt-project/
-├── lang/
-│   ├── en-US.json
-│   ├── es-ES.js
-│   ├── fr-FR.ts
+├── i18n/
+│   ├── locales/
+│   │   ├── en-US.json
+│   │   ├── es-ES.js
+│   │   ├── fr-FR.ts
 ├── nuxt.config.ts
 ```
 
@@ -46,7 +46,6 @@ export default defineNuxtConfig({
       }
     ],
     lazy: true,
-    langDir: 'lang',
     defaultLocale: 'en'
   }
 })
@@ -97,12 +96,13 @@ The following is an example of a lang directory containing locale files for the
 
 ```
 nuxt-project/
-├── lang/
-│   ├── es.json     # locale messages for common Spanish
-│   ├── es-AR.json  # locale messages for Argentina
-│   ├── es-UY.json  # locale messages for Uruguay
-│   ├── es-US.json  # locale messages for Estados Unidos
-|   ...             # other countries ...
+├── i18n/
+│   ├── locales/
+│   │   ├── es.json     # locale messages for common Spanish
+│   │   ├── es-AR.json  # locale messages for Argentina
+│   │   ├── es-UY.json  # locale messages for Uruguay
+│   │   ├── es-US.json  # locale messages for Estados Unidos
+|   |   ...             # other countries ...
 ├── nuxt.config.ts
 ```
 
@@ -135,7 +135,6 @@ export default defineNuxtConfig({
       }
     ],
     lazy: true,
-    langDir: 'lang',
     defaultLocale: 'en'
   }
 })
@@ -187,7 +186,6 @@ export default defineNuxtConfig({
       }
     ],
     lazy: true,
-    langDir: 'lang',
     defaultLocale: 'en'
   }
 })

docs/content/docs/5.v9/3.options/10.misc.md

@@ -64,3 +64,10 @@ Don't enable this option in production. It's not optimized for it.
 - default: `false`
 
 Set the plugin as `parallel`. See [nuxt plugin loading strategy](https://nuxt.com/docs/guide/directory-structure/plugins#loading-strategy).
+
+## `restructureDir`
+
+- type: `string`
+- default: `i18n`
+
+Can be used to configure the directory used to resolve i18n files.

docs/content/docs/5.v9/3.options/3.lazy.md

@@ -10,18 +10,18 @@ description: Lazy loading options.
 
 See also [Lazy-load translations](/docs/guide/lazy-load-translations).
 
-Whether the translations should be lazy-loaded. If this is enabled, you MUST configure the `langDir` option, and locales must be an array of objects, each containing a `file` or `files` key.
+Whether the translations should be lazy-loaded. If this is enabled, locales must be an array of objects, each containing a `file` or `files` key.
 
 Loading locale messages lazily means that only messages for currently used locale (and for the fallback locale, if different from current locale) will be loaded on page loading.
 
 ## `langDir`
 
-- type: `string` or `null`
-- default: `null`
+- type: `string`
+- default: `locales`
 
 A relative path to a directory containing translation files to load. Can be used with or without lazy-loading (the `lazy` option).
 
-The path is resolved relative to the project `srcDir` (project root by default).
+The path is resolved relative to the project `restructureDir` at the root of a project ('i18n' by default).
 
 ::callout{icon="i-heroicons-exclamation-triangle" color="amber"}
 Absolute paths will fail in production (eg. `/locales` should be changed into either `locales` or `./locales`)