Version Packages

Previously VIntl for Nuxt kept track of files that were used as locale
messages and matched module IDs based on them. This, however, was very
unreliable in certain environments.

With this change VIntl for Nuxt now uses 'markers', URL parameters added
to the end of imported module IDs. This allows it to very quickly test
whether a specific module is imported through a message file and should
be processed by the VIntl unplugin.

.github/workflows/release.yml

@@ -22,10 +22,10 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Set up Node.js
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: 18.x
 

.github/workflows/test.yml

@@ -10,10 +10,10 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v3
+        uses: actions/checkout@v4
 
       - name: Set up Node.js
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
           node-version: 18.x
 

apps/docs/content/1.introduction/1.configuration.md

@@ -22,6 +22,7 @@ Represents the VIntl module options.
 | `hostLanguageParam`     | `'hl'`  | **Deprecated.** An optional name of the query parameter used to override the user language (including automatically detected one). It is used to generate SEO meta tags. Using `null` will disable them.                                                                           |
 | `parserless`            | `<...>` | An optional [`ParserlessOptions`] object or [`ParserlessMode`] which configures the parserless mode.                                                                                                                                                                               |
 | `seo`                   | `<...>` | An optional [`SEOOptions`] object which configures automatic head tags to improve discoverability of other languages by search engines.                                                                                                                                            |
+| `onParseError`          |         | An optional [`ParsingErrorHandlingOption`] value that defines how to handle errors that occur when transforming message files. If not defined, the errors are not handled and thrown during the building, preventing it from succeeding.                                           |
 
 [`BroadcastChannel`]: https://developer.mozilla.org/en-US/docs/Web/API/BroadcastChannel
 [`ParserlessOptions`]: #parserlessoptions
@@ -161,3 +162,23 @@ By default VIntl will add `<link>` tags for every language to make search engine
 | `baseURL`                   |         | **Recommended.** An optional string value representing the base URL of the site. If not set, VIntl will try to guess the URL based on inital request URL or the current `window.location`.                                                                                                              |
 | `defaultLocaleHasParameter` | `true`  | A boolean value representing whether the default locale should have a host language parameter. Disabling this may make URLs of visitors cleaner, however it is not correct, because lack of host language instructs VIntl to use user's language (either the one they've used before or browser's one). |
 | `xDefaultHreflang`          | `true`  | A boolean value representing whether the `x-default` hreflang is present.                                                                                                                                                                                                                               |
+
+## `ParsingErrorHandlingOption`
+
+[`ParsingErrorHandlingOption`]: #parsingerrorhandlingoption
+
+Represents a value for the message pasing error handling option.
+
+It can be one of the following:
+
+- A string containing a name of the strategy for handling the errors. The following strategies are available:
+
+  | Name                     | Strategy                                                                          |
+  | :----------------------- | :-------------------------------------------------------------------------------- |
+  | `use-message-as-literal` | Use the raw message contents as a literal.                                        |
+  | `use-id-as-literal`      | Use the message ID as a literal.                                                  |
+  | `use-empty-literal`      | Use empty string as a literal.                                                    |
+  | `log-and-skip`           | Log the error to console and don't include the message into the transformed file. |
+  | `skip`                   | Skip including the message into the transformed file.                             |
+
+- An function that takes in a context for the error (that includes error itself) and optionally returns a fallback AST (not returning anything skips including the message into the transformed file).

apps/docs/nuxt.config.ts

@@ -1,5 +1,5 @@
 export default defineNuxtConfig({
-  extends: '@nuxt-themes/docus',
+  extends: ['@nuxt-themes/docus'],
   modules: ['@vintl/nuxt'],
   vintl: {
     defaultLocale: 'en-US',

apps/docs/package.json

@@ -13,15 +13,15 @@
     "start": "node .output/server/index.mjs"
   },
   "devDependencies": {
-    "@formatjs/cli": "^6.1.2",
-    "@nuxt-themes/docus": "^1.12.3",
-    "@nuxt/eslint-config": "^0.1.1",
+    "@formatjs/cli": "^6.2.4",
+    "@nuxt-themes/docus": "^1.15.0",
+    "@nuxt/eslint-config": "^0.2.0",
     "@vintl-dev/eslint-config-peony": "workspace:^",
     "@vintl/nuxt": "workspace:^",
-    "eslint": "^8.42.0",
-    "nuxi": "^3.5.3",
-    "nuxt": "^3.5.3",
-    "theme-colors": "^0.0.5",
-    "vue": "^3.3.4"
+    "eslint": "^8.54.0",
+    "nuxi": "^3.9.1",
+    "nuxt": "^3.8.1",
+    "theme-colors": "^0.1.0",
+    "vue": "^3.3.8"
   }
 }

apps/docs/plugins/global-vintl.ts

@@ -0,0 +1,24 @@
+export default defineNuxtPlugin((nuxtApp) => {
+  if (process.client && typeof window !== 'undefined') {
+    Object.defineProperty(window, 'vintl', {
+      configurable: true,
+      writable: true,
+      enumerable: true,
+      value: nuxtApp.$i18n,
+    })
+    console.log('~'.repeat(80))
+    console.log('%cHey there! 👋', 'font-size: 1.2rem')
+    console.log(
+      'VIntl controller can be used here through a global `vintl` variable.',
+    )
+    console.log(
+      'Have playing with it! And if you break anything, just refresh the page :P',
+    )
+    if (!process.dev) {
+      console.log(
+        '⚠️ This is a production environment. Message parsing is unavailable.',
+      )
+    }
+    console.log('~'.repeat(80))
+  }
+})

apps/playground/locales/en-US.json

@@ -1,4 +1,7 @@
 {
+  "broken-message": {
+    "message": "This is {broken, }"
+  },
   "example": {
     "message": "Example"
   },

apps/playground/nuxt.config.ts

@@ -39,5 +39,19 @@ export default defineNuxtConfig({
       xDefaultHreflang: false,
       defaultLocaleHasParameter: false,
     },
+    onParseError: 'log-and-skip',
   },
+  typescript: {
+    tsConfig: {
+      compilerOptions: {
+        moduleResolution: 'bundler',
+      },
+    },
+  },
+  plugins: [
+    {
+      src: './plugins/test.ts',
+      order: -100,
+    },
+  ],
 })

apps/playground/package.json

@@ -17,8 +17,8 @@
     "@vintl-dev/eslint-config-peony": "workspace:^",
     "@vintl-dev/pg-messages": "workspace:^",
     "@vintl/nuxt": "workspace:^",
-    "eslint": "^8.42.0",
-    "nuxi": "^3.5.3",
-    "nuxt": "^3.5.3"
+    "eslint": "^8.54.0",
+    "nuxi": "^3.9.1",
+    "nuxt": "^3.8.1"
   }
 }

apps/playground/pages/index.vue

@@ -27,6 +27,10 @@ const messages = defineMessages({
     id: 'index.use-automatic',
     defaultMessage: 'Use automatic',
   },
+  brokenMessage: {
+    id: 'broken-message',
+    defaultMessage: 'This is {broken, }',
+  },
 } as const)
 
 const vintl = useVIntl()
@@ -85,10 +89,9 @@ const useAutomatic = computed({
             id="language-select"
             v-model="currentLocale"
             :disabled="vintl.automatic"
-            @change="onLocaleChange"
           >
             <option
-              v-for="locale in [...$nuxt.$i18n.$locales.value.keys()]"
+              v-for="locale in [...$i18n.$locales.value.keys()]"
               :key="locale.tag"
               :value="locale.tag"
             >

apps/playground/plugins/test.ts

@@ -0,0 +1,9 @@
+export default defineNuxtPlugin((nuxtApp) => {
+  nuxtApp.hook('i18n:extendLocale', ({ event }) => {
+    console.log('[vintl] loading locale', event.locale.tag)
+  })
+
+  nuxtApp.hook('i18n:ready', () => {
+    console.log('[vintl] ready')
+  })
+})

package.json

@@ -7,8 +7,8 @@
     "packages/*"
   ],
   "devDependencies": {
-    "@changesets/cli": "^2.26.1",
-    "turbo": "^1.10.1"
+    "@changesets/cli": "^2.26.2",
+    "turbo": "^1.10.16"
   },
   "scripts": {
     "pg:prepare": "turbo run --no-daemon @vintl-dev/pg#dev:prepare",
@@ -36,5 +36,5 @@
       }
     }
   },
-  "packageManager": "pnpm@8.6.1"
+  "packageManager": "pnpm@8.10.5"
 }

packages/eslint-config/package.json

@@ -26,14 +26,14 @@
     "config.json"
   ],
   "dependencies": {
-    "@rushstack/eslint-patch": "^1.3.0",
-    "@typescript-eslint/eslint-plugin": "^6.3.0",
-    "@typescript-eslint/parser": "^6.3.0",
-    "eslint-plugin-vue": "^9.14.1",
-    "typescript": "^5.1.3"
+    "@rushstack/eslint-patch": "^1.5.1",
+    "@typescript-eslint/eslint-plugin": "^6.11.0",
+    "@typescript-eslint/parser": "^6.11.0",
+    "eslint-plugin-vue": "^9.18.1",
+    "typescript": "^5.2.2"
   },
   "devDependencies": {
-    "@types/eslint": "^8.40.0",
-    "eslint": "^8.42.0"
+    "@types/eslint": "^8.44.7",
+    "eslint": "^8.54.0"
   }
 }

packages/vintl-nuxt/CHANGELOG.md

@@ -1,5 +1,69 @@
 # @vintl/nuxt
 
+## 1.8.1
+
+### Patch Changes
+
+- 114d04a: Switched to a slightly more compatible `#app` augmentation
+
+## 1.8.0
+
+### Minor Changes
+
+- 9d939c1: Switched to using module ID markers
+
+  Previously VIntl for Nuxt kept track of files that were used as locale messages and matched module IDs based on them. This, however, was very unreliable in certain environments.
+
+  With this change VIntl for Nuxt now uses ‘markers’, URL parameters added to the end of imported module IDs. This allows it to very quickly test whether a specific module is imported through a message file and should be processed by the VIntl unplugin.
+
+## 1.7.1
+
+### Patch Changes
+
+- 6479891: VIntl updated to the latest version
+
+  Latest version of VIntl fixes missing type declarations for global properties, like `$t`, `$fmt` and `$i18n`.
+
+  We might add automatic handling for disabling of `controllerOpts.globalMixin` in the future releases. You can follow the status update in [#74](https://github.com/vintl-dev/nuxt/issues/74).
+
+  For now, if you disable global mixin, use the below augmentation to disable these unusable properties:
+
+  ```ts
+  declare global {
+    namespace VueIntlController {
+      interface Options {
+        globalMixin: false
+      }
+    }
+  }
+  ```
+
+## 1.7.0
+
+### Minor Changes
+
+- a9fdc59: Add support for parsing the messages in the error handlers
+
+  With [update to `@vintl/unplugin`](https://github.com/vintl-dev/unplugin/releases/tag/v1.5.0), it's now possible to use `parseMessage` from the error handler's context to parse custom messages or re-parse the current message with any modified options.
+
+## 1.6.0
+
+### Minor Changes
+
+- 81c23b0: Support for parsing error handling
+
+  `@vintl/nuxt` can now handle errors when parsing message files containing broken messages in a configurable manner.
+
+  You can configure how errors are handled using `onParseError` module option, which can either be a name of the built-in strategy, or a function that takes in context and optionally provides fallback message AST.
+
+  Check out documentation for more information.
+
+### Patch Changes
+
+- 2b5a59b: Unpin FormatJS dependencies
+
+  We proveviously had `@formatjs/intl` pinned because of the broken ESM migration, however this has been fixed for quite some time already, so the pinned version has been to changed to a range, which ensures that `@formatjs/intl` can be updated with latest bug fixes and improvements until the next major version.
+
 ## 1.5.0
 
 ### Minor Changes

packages/vintl-nuxt/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vintl/nuxt",
-  "version": "1.5.0",
+  "version": "1.8.1",
   "description": "Nuxt Module for VIntl integration",
   "keywords": [
     "i18n",
@@ -34,36 +34,36 @@
     "dist"
   ],
   "scripts": {
-    "build": "nuxt-module-build",
+    "build": "nuxt-module-build build",
     "lint": "eslint --cache .",
     "prepack": "pnpm run -s lint && pnpm run -s build"
   },
   "devDependencies": {
-    "@nuxt/module-builder": "^0.4.0",
-    "@nuxt/schema": "^3.5.3",
-    "@types/hash-sum": "^1.0.0",
-    "@types/node": "^18.16.16",
-    "@unhead/vue": "^1.1.27",
+    "@nuxt/module-builder": "^0.5.4",
+    "@nuxt/schema": "^3.8.1",
+    "@types/hash-sum": "^1.0.2",
+    "@types/node": "^18.18.10",
+    "@unhead/vue": "^1.8.4",
     "@vintl-dev/eslint-config-peony": "workspace:^",
     "hookable": "^5.5.3",
-    "prettier-plugin-jsdoc": "^0.4.2",
-    "typescript": "^5.1.3",
-    "vue-router": "^4.2.4"
+    "prettier-plugin-jsdoc": "^1.1.1",
+    "typescript": "^5.2.2",
+    "vue-router": "^4.2.5"
   },
   "dependencies": {
-    "@formatjs/intl": "2.7.2",
-    "@formatjs/intl-localematcher": "^0.4.0",
-    "@nuxt/kit": "^3.5.3",
-    "@vintl/unplugin": "^1.2.4",
-    "@vintl/vintl": "^4.2.1",
+    "@formatjs/intl": "^2.9.9",
+    "@formatjs/intl-localematcher": "^0.5.2",
+    "@nuxt/kit": "^3.8.1",
+    "@vintl/unplugin": "^1.5.1",
+    "@vintl/vintl": "^4.4.1",
     "astring": "^1.8.6",
-    "consola": "^3.1.0",
+    "consola": "^3.2.3",
     "hash-sum": "^2.0.0",
-    "import-meta-resolve": "^3.0.0",
+    "import-meta-resolve": "^3.1.1",
     "pathe": "^1.1.1",
     "picocolors": "^1.0.0",
     "slash": "^5.1.0",
-    "ufo": "^1.1.2",
+    "ufo": "^1.3.2",
     "zod": "^3.21.4"
   }
 }

packages/vintl-nuxt/src/module.ts

@@ -96,7 +96,7 @@ export default defineNuxtModule<ModuleOptions>({
               return resolveInResDir(specifier).relativeTo(optionsFile.dst)
             },
             registerMessagesFile(file, importPath) {
-              pluginOptionsBank.registerFile(
+              return pluginOptionsBank.registerFile(
                 file,
                 resolvePath(dirname(optionsFile.dst), importPath),
               )
@@ -124,11 +124,31 @@ export default defineNuxtModule<ModuleOptions>({
 
       const { icuMessages } = await import('@vintl/unplugin')
 
+      const onParseError = (() => {
+        let { onParseError } = options
+
+        if (onParseError === 'log-and-skip') {
+          onParseError = (ctx) => {
+            consola.warn(
+              `[vintl] Cannot parse the message "${
+                ctx.messageId
+              }" in "${relativizePath(
+                nuxt.options.srcDir,
+                ctx.moduleId,
+              )}". It will me skipped.`,
+            )
+          }
+        }
+
+        return onParseError
+      })()
+
       extendWebpackConfig((cfg) => {
         const plugins = (cfg.plugins ??= [])
         plugins.push(
           ...pluginOptionsBank
             .createOptions({
+              onParseError,
               output: {
                 type: parserlessModeEnabled ? 'ast' : 'raw',
               },
@@ -143,6 +163,7 @@ export default defineNuxtModule<ModuleOptions>({
           ...pluginOptionsBank
             .createOptions({
               pluginsWrapping: true,
+              onParseError,
               output: {
                 type: parserlessModeEnabled ? 'ast' : 'raw',
               },

packages/vintl-nuxt/src/options-gen.ts

@@ -623,11 +623,12 @@ interface GeneratorContext {
    *
    * @param file Input message file options.
    * @param importPath Resolved path.
+   * @returns Marked import path.
    */
   registerMessagesFile(
     file: t.output<typeof messagesImportSourceSchema>,
     importPath: string,
-  ): void
+  ): string
 
   /**
    * Resolves a module from the runtime directory.
@@ -780,8 +781,10 @@ export function generate(
 
     for (const messageFile of files) {
       const { from: importPath, name: importKey } = messageFile
-      const resolvedPath = resolve(messageFile.from)
-      registerMessagesFile(messageFile, resolvedPath)
+      const resolvedPath = registerMessagesFile(
+        messageFile,
+        resolve(messageFile.from),
+      )
 
       if (isDefaultLocale) {
         // if import key is 'default' then:

packages/vintl-nuxt/src/parser-bank.ts

@@ -12,9 +12,36 @@ import type {
 
 type UniqueOptions = t.output<typeof messagesImportOptionsSchema>
 
+class Marker {
+  private readonly regExp: RegExp
+
+  public constructor(public readonly marker: string) {
+    this.regExp = new RegExp(`(\\?|&)${marker}(&|$)`)
+  }
+
+  public apply(id: string) {
+    return `${id}${id.includes('?') ? '&' : '?'}${this.marker}`
+  }
+
+  public matches(id: string) {
+    return this.regExp.test(id)
+  }
+}
+
+class MarkedFileSet extends Set<string> {
+  public readonly marker: Marker
+
+  constructor(marker: Marker, iterable?: Iterable<string> | null | undefined) {
+    super(iterable)
+    this.marker = marker
+  }
+}
+
 export class PluginOptionsBank {
   // let the uniqueOptions be a map of unique options to a list of files that have the same options
-  private readonly filesByOptions: Map<UniqueOptions, Set<string>> = new Map()
+  private readonly filesByOptions = new Map<UniqueOptions, MarkedFileSet>()
+
+  private incrementingMarker = 0
 
   private findOrCreateFileSet(optionsVariation: UniqueOptions) {
     for (const [knownOptionsVariation, files] of this.filesByOptions) {
@@ -31,7 +58,9 @@ export class PluginOptionsBank {
       parser: optionsVariation.parser,
     }
 
-    const fileSet = new Set<string>()
+    const marker = new Marker(`icu-messages-${this.incrementingMarker++}`)
+
+    const fileSet = new MarkedFileSet(marker)
     this.filesByOptions.set(filteredOptions, fileSet)
     return fileSet
   }
@@ -40,7 +69,8 @@ export class PluginOptionsBank {
     file: t.output<typeof messagesImportSourceSchema>,
     resolvedPath: string,
   ) {
-    this.findOrCreateFileSet(file).add(resolvedPath)
+    const { marker } = this.findOrCreateFileSet(file).add(resolvedPath)
+    return marker.apply(resolvedPath)
   }
 
   public createOptions<T extends { name: string }>(
@@ -49,7 +79,7 @@ export class PluginOptionsBank {
     const options: PluginOptions<T>[] = []
 
     for (const [{ format, parser }, files] of this.filesByOptions) {
-      const filter = (id: string) => files.has(id)
+      const filter = (id: string) => files.marker.matches(id)
 
       options.push({
         ...baseOptions,

packages/vintl-nuxt/src/runtime/plugin.ts

@@ -163,7 +163,7 @@ type EventContext<E> = {
   controller: IntlController<MessageValueType>
 }
 
-declare module 'nuxt/app' {
+declare module '#app' {
   interface NuxtApp
     extends InjectedProperties<VueIntlController.MessageValueTypes> {}
 

packages/vintl-nuxt/src/schemas/module-options.ts

@@ -3,6 +3,27 @@ import { tSwitch } from '../utils/zod-utils.js'
 import { languageTagSchema } from './language-tag.js'
 import { localeDescriptorSchema } from './locales.js'
 import { seoOptions } from './seo.js'
+import type { ParseErrorHandler } from '@vintl/unplugin'
+
+const parseErrorHandingStrategy = t.union([
+  t.literal('use-message-as-literal'),
+  t.literal('use-id-as-literal'),
+  t.literal('use-empty-literal'),
+  t.literal('log-and-skip'),
+  t.literal('skip'),
+])
+
+const parseErrorHandler = t.custom<ParseErrorHandler>(
+  (value) => typeof value === 'function',
+)
+
+export const parseErrorHandling = tSwitch((input) => {
+  if (typeof input === 'function') {
+    return parseErrorHandler
+  } else if (typeof input === 'string') {
+    return parseErrorHandingStrategy
+  }
+})
 
 const parselessModeEnumSchema = t.enum(['always', 'only-prod', 'never'])
 
@@ -200,6 +221,14 @@ export const moduleOptionsSchema = t
         return parselessOptionsSchema
       }
     }).default('only-prod'),
+
+    /**
+     * Either a literal name of the strategy or a function that handles the
+     * errors that occur during the parsing of one of the imported files.
+     *
+     * @see https://github.com/vintl-dev/unplugin/blob/df9b3be9c77f78eaf5fe7f8d6fde1655f2bc79e1/README.md#onparseerror
+     */
+    onParseError: parseErrorHandling.optional(),
   })
   .transform((from) => {
     if (from.seo === undefined) {

packages/vintl-nuxt/stubs/app.d.ts

@@ -0,0 +1 @@
+export * from 'nuxt/app'

packages/vintl-nuxt/tsconfig.runtime.json

@@ -10,7 +10,8 @@
 
     "outDir": "./dist",
     "paths": {
-      "#imports": ["./stubs/imports.js"]
+      "#imports": ["./stubs/imports.js"],
+      "#app": ["./stubs/app.js"]
     }
   },
   "include": [

turbo.json

@@ -7,8 +7,11 @@
     "@vintl/nuxt#lint": {
       "outputs": [".eslintcache"]
     },
+    "@vintl-dev/pg#intl:extract": {
+      "outputs": ["./locales/en-US.json"]
+    },
     "@vintl-dev/pg#dev:prepare": {
-      "dependsOn": ["@vintl/nuxt#build"],
+      "dependsOn": ["@vintl/nuxt#build", "@vintl-dev/pg#intl:extract"],
       "inputs": ["./package.json", "./nuxt.config.ts"],
       "outputs": [".nuxt"]
     },