feat: support js and ts extension resource formats (#1938)

* docs: typos * feat: support js and ts extension resource formats * add server handler skelton * feat: support js and ts extension resource formats * add server handler skelton * basic implementation * refactor * support ssg * update snapshot * bump * fix: change to $config using * fix: strip type annotation on typescript codes * refactoring * docs: updates * fix: updates * fix: more updates * add defineI18nLocale * remove unnecesary deps * add `precompile` options * fix: update snapshots * chore: bump deps * docs: updates * refactor: remove codes --------- Co-authored-by: pierresaid <[email protected]> Co-authored-by: Inesh Bose <[email protected]>
nuxt-modules · Mar 23, 2023 · c0b701c · c0b701c
1 parent 7943ca1
commit c0b701c
Show file tree

Hide file tree

Showing 49 changed files with 3,264 additions and 848 deletions.
diff --git a/TODO.md b/TODO.md
@@ -1,7 +1,7 @@
 # TODO
 
 - [ ] `skipNuxtState`
-- [ ] executalbe files (`js`, `cjs`, and `mjs`) are not supported yet
+- [x] executalbe files (`js`, `cjs`, and `mjs`) are not supported yet
 - [ ] `sortRoutes` option
 - [x] `vueI18n` option for function
 - Refactoring

diff --git a/build.config.ts b/build.config.ts
@@ -1,5 +1,5 @@
 import { defineBuildConfig } from 'unbuild'
 
 export default defineBuildConfig({
-  externals: ['node:fs', 'node:url', '@intlify/vue-i18n-bridge', 'webpack']
+  externals: ['node:fs', 'node:url', '@intlify/vue-i18n-bridge', 'webpack', '@babel/parser']
 })
diff --git a/docs/content/2.guide/15.migrating.md b/docs/content/2.guide/15.migrating.md
@@ -153,6 +153,7 @@ This option is no longer necessary, because i18n custom block is supported by [u
 
 These functions can now be triggered using Nuxt runtime hooks. Please refer to [runtime hooks](/guide/runtime-hooks) to see how to use these.
 
+
 ### Change some export APIs name on Nuxt context
 
 The following API will be changed to `$`:
@@ -166,7 +167,7 @@ The following API will be changed to `$`:
 
 ### Deprecated export APIs in Vuex
 
-Vuex extention APIs were removed, because Vuex no longer requires in Nuxt3.
+Vuex extension APIs were removed, because Vuex no longer requires in Nuxt3.
 
 The following APIs are no longer available:
 

diff --git a/docs/content/2.guide/8.lazy-load-translations.md b/docs/content/2.guide/8.lazy-load-translations.md
@@ -12,13 +12,7 @@ To enable translations lazy-loading, follow these steps when configuring **Nuxt
 - Set `langDir` option to the directory (can not be empty) that contains your translation files.
 - Configure `locales` option as an array of object, 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 `vueI18n` option.
-- Each `file` can return either an `Object`.
-
-::alert{type="warning"}
-
-`file` or `files` is still not supported `function` , Promises
-
-::
+- Each `file` or `files` can return either an `Object`, or a function that returns `Promise` must return `Object`.
 
 ## Basic usage
 
@@ -28,14 +22,14 @@ Example files structure:
 nuxt-project/
 ├── lang/
 │   ├── en-US.json
-│   ├── es-ES.json
-│   ├── fr-FR.json
+│   ├── es-ES.js
+│   ├── fr-FR.ts
 ├── nuxt.config.ts
 ```
 
 Configuration example:
 
-```js {}[nuxt.config.ts]
+```ts {}[nuxt.config.ts]
 export default defineNuxtConfig({
   // ...
 
@@ -47,11 +41,11 @@ export default defineNuxtConfig({
       },
       {
         code: 'es',
-        file: 'es-ES.json'
+        file: 'es-ES.js'
       },
       {
         code: 'fr',
-        file: 'fr-FR.json'
+        file: 'fr-FR.ts'
       }
     ],
     lazy: true,
@@ -63,12 +57,50 @@ export default defineNuxtConfig({
 })
 ```
 
-::alert{type="warning"}
+```ts {}[lang/fr-FR.ts]
+export default defineI18nLocale(async (context, locale) => {
+  return {
+    welcome: 'Welcome'
+  }
+})
+
+// or
+
+export default {
+  welcome: 'Welcome'
+}
+```
+
+::alert{type="info"}
+
+If your function returns an object of locale messages, **you must define it in the `defineI18nLocale` composable function**.
+
+About `defineI18nLocale` details, see the [here](/api/composables#defineI18nLocale).
 
-Currently, `json`,`json5` and `yaml` are supported only.
+::
+
+::alert{type="warn"}
+
+The js / ts format is currently an experimental feature and disabled by default. 
+
+If you want to use it, you must set the `experimental.jsTsFormatResource` module option to `true`.
 
 ::
 
+::alert{type="info"}
+
+If the function returns an Object available in nuxt i18n module, you can configure the dynamic locale messages, like the API (including external API) or back-end, via fetch:
+
+```js
+export default defineI18nLocale((context, locale) => {
+  // for example, fetch locale messages from nuxt server
+  return $fetch(`/api/${locale}`)
+})
+```
+
+::
+
+
 ## Multiple files lazy loading
 
 The `files` can load lazily multiple files.

diff --git a/docs/content/3.options/3.lazy.md b/docs/content/3.options/3.lazy.md
@@ -24,13 +24,6 @@ Loading locale messages lazily means that only messages for currently used local
 
 ::
 
-The value can also be set to an object instead of the value `true` to override configuration options related to lazy loading. Supports the following optional properties:
-
-- type: `boolean`
-- default: `true`
-
-Whether the translation messages for the current locale should be injected into Nuxt state and re-used on the client-side. [Read more](/guide/lazy-load-translations#lazy-configuration-options).
-
 ## `langDir`
 
 - type: `string` or `null`
@@ -41,5 +34,7 @@ A relative path to a directory containing translation files to load. Can be used
 The path is resolved relative to the project `srcDir` (project root by default).
 
 ::alert{type="warning"}
+
 Absolute paths will fail in production (eg. `/locales` should be changed into either `locales` or `./locales`)
+
 ::
diff --git a/docs/content/3.options/6.misc.md b/docs/content/3.options/6.misc.md
@@ -4,6 +4,47 @@ Miscellaneous options.
 
 ---
 
+## `experimental`
+
+- type: `object`
+- default: `{ jsTsFormatResource: false }`
+
+Configure the flag for experimental features of the nuxt i18n module.
+
+::alert{type="info"}
+
+This module option setting is also set to the runtime config.
+
+::
+
+Supported properties:
+
+- `jsTsFormatResource` (default: `false`) - Allow the format `js` and `ts` for locale messages in lazy load translation.
+
+
+## `precompile`
+
+- type: `object`
+- default: `{ strictMessage: true, escapeHtml: false }`
+
+Configure flags that sets the behavior precompilation of locale messages.
+
+Supported properties:
+
+- `strictMessage` (default: `true`) Strictly check that the locale message does not contain HTML tags. If HTML tags are included, an error is thrown.
+  ::alert{type="warning"}
+
+  If you do not want the error to be thrown, you can work around it by setting it to false. However, **this means that the locale message might cause security issues with XSS**. In that case, we recommend setting the `escapeHtml` option to `true`. 
+
+  ::
+
+- `escapeHtml` (default: `false`) - Determine whether to escape HTML tags if they are included in the locale message.
+  ::alert{type="warning"}
+
+  If `strictMessage` is disabled by setting it to `false`, we recommend enabling this option.
+
+  ::
+
 ## `types`
 
 - type: `string` (`composition` or `legacy`) | `undefined`

diff --git a/docs/content/3.options/7.runtime-config.md b/docs/content/3.options/7.runtime-config.md
@@ -8,40 +8,56 @@ Some options can be set via the `runtimeConfig`, setting options this way makes
 
 If you want to use environment variables to change [supported options](#supported-options), you will have to set these in `runtimeConfig.public.i18n`. 
 
-The module configuration takes precedence, options set through `runtimeConfig` will only be used if they are unset.
-
-Setting `baseUrl` through `runtimeConfig` would look like this:
-
 ```ts {}[nuxt.config.ts]
 export default defineNuxtConfig({
-  runtimeConfig: {
-    public: {
-      i18n: {
-         baseUrl: 'https://example.com',
-      }
-    }
-  },
   modules: [
     '@nuxtjs/i18n'
   ],
   i18n: {
     // Leave options unset that you want to set using `runtimeConfig`
     // baseUrl: 'https://example.com',
+  },
+  runtimeConfig: {
+    public: {
+      i18n: {
+         baseUrl: 'https://example.com',
+         // smothing other options ...
+      }
+    }
   }
 })
 ```
 
-With this configuration you will be able to override the `baseUrl` option by setting the `NUXT_PUBLIC_I18N_BASE_URL` environment variable. You can read more about how this works in the [Nuxt documentation](https://nuxt.com/docs/guide/going-further/runtime-config#environment-variables).
+You can read more about how this works in the [Nuxt documentation](https://nuxt.com/docs/guide/going-further/runtime-config#environment-variables).
 
-##  Supported options
-
-These options can be set using `runtimeConfig`:
-* [`baseUrl`](./routing#baseUrl)
 
 ::alert{type=warning}
+
 Only [serializable values are supported](https://nuxt.com/docs/guide/going-further/runtime-config#serialization) in `runtimeConfig`, options set this way may not support all available types (such as functions) as would normally be possible using the default configuration.
+
 ::
 
 ::alert{type=info}
+
 If you would like other options to be supported, open an issue describing your use case, or open a PR adding to add support yourself!
+
+::
+
+
+## Supported options
+
+These options can be set using `runtimeConfig`:
+
+### `baseUrl`
+
+This runtime config option is same the [`baseUrl`](./routing#baseUrl) module option. 
+
+The module configuration takes precedence, options set through `runtimeConfig` will only be used if they are unset.
+
+::alert{type=warning}
+
+Note that the `baseUrl` module option allows you to set the function, but the runtime config does not due to limitations.
+
 ::
+
+With this configuration you will be able to override the `baseUrl` option by setting the `NUXT_PUBLIC_I18N_BASE_URL` environment variable.
diff --git a/docs/content/4.API/1.composables.md b/docs/content/4.API/1.composables.md
@@ -176,3 +176,47 @@ Note that if the value of `detectBrowserLanguage.useCookie` is `false`, an **emp
 ```ts
 declare function useCookieLocale(): Ref<string>;
 ```
+
+## `defineI18nLocale`
+
+The `defineI18nLocale` defines a composable function to dynamically load locale messages.
+
+This function is used to dynamically load a locale with [lazy-load translations](/guide/lazy-load-translations).
+
+You can use at JavaScript and TypeScript extension formats.
+
+You need return locale messags object that will be resolved by Promise.
+
+### Type
+
+```ts
+declare function defineI18nLocale<Messages = LocaleMessages<DefineLocaleMessage>, Locales = Locale>(loader: (context: NuxtApp, locale: Locales) => Messages | Promise<Messages>): (context: NuxtApp, locale: Locales) => Messages | Promise<Messages>;
+```
+
+for example, locale loading with fetch:
+```ts
+export default defineI18nLocale((context, locale) => {
+  return $fetch(`https://your-company-product/api/${locale}`)
+})
+```
+
+### Parameters
+
+#### `loader`
+
+A function that is the dynamic locale messages loading, that has the following parameters:
+
+- `context`
+
+  **Type**: `NuxtApp`
+
+  A Nuxt Application instance that is passed from nuxt i18n module.
+
+- `locale`
+
+  **Type**: `Locale`
+
+  A target locale that is passed from nuxt i18n module. That is passed when the locale is switched in the following cases:
+
+  - when you switch the locale with `setLocale`.
+  - when the locale is switched with `<NuxtLink>`. for example, the route path resolved by `useSwitchLocalePath` or `$switchLocalePath`.