Skip to content

Commit

Permalink
feat: configurable directory restructure (#3054)
Browse files Browse the repository at this point in the history
* 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
  • Loading branch information
BobbieGoede authored Aug 8, 2024
1 parent be59c76 commit 08638d7
Show file tree
Hide file tree
Showing 34 changed files with 2,017 additions and 523 deletions.
11 changes: 11 additions & 0 deletions docs/content/docs/3.options/10.misc.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
::
9 changes: 3 additions & 6 deletions docs/content/docs/5.v9/2.guide/14.layers.md
Original file line number Diff line number Diff line change
Expand Up @@ -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' }
Expand All @@ -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' }]
}
})
Expand All @@ -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' }
Expand All @@ -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"
Expand Down
4 changes: 2 additions & 2 deletions docs/content/docs/5.v9/2.guide/15.server-side-translations.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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'
}
}
})
Expand Down
25 changes: 25 additions & 0 deletions docs/content/docs/5.v9/2.guide/18.breaking-changes-in-v9.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
26 changes: 12 additions & 14 deletions docs/content/docs/5.v9/2.guide/7.lazy-load-translations.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand All @@ -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
```

Expand All @@ -46,7 +46,6 @@ export default defineNuxtConfig({
}
],
lazy: true,
langDir: 'lang',
defaultLocale: 'en'
}
})
Expand Down Expand Up @@ -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
```

Expand Down Expand Up @@ -135,7 +135,6 @@ export default defineNuxtConfig({
}
],
lazy: true,
langDir: 'lang',
defaultLocale: 'en'
}
})
Expand Down Expand Up @@ -187,7 +186,6 @@ export default defineNuxtConfig({
}
],
lazy: true,
langDir: 'lang',
defaultLocale: 'en'
}
})
Expand Down
7 changes: 7 additions & 0 deletions docs/content/docs/5.v9/3.options/10.misc.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
8 changes: 4 additions & 4 deletions docs/content/docs/5.v9/3.options/3.lazy.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`)
Expand Down
Loading

0 comments on commit 08638d7

Please sign in to comment.