fix(nuxt): require locale mapping for i18n integration (#1462)

This PR fixes an issue with the registration order warning of the nuxt
module.
It also requires the user to specify a mapping for onyx locales to the
locales from nuxt-i18n specific to their project.
This fixes a bug where all projects would display all locales of onyx as
supported languages even if they were not specified within the project.
An issue and PR were already created for nuxt-i18n to support loading
locales from npm packages.
(nuxt-modules/i18n#2999)
This way it would be possible to decouple onyx and nuxt-i18n while
preserving easy support and customizability. This PR should make the
onyx module useable until the feature is available inside nuxt-i18n.

.changeset/nasty-planes-search.md

@@ -0,0 +1,5 @@
+---
+"@sit-onyx/nuxt": patch
+---
+
+Only show registration order warning if nuxt-i18n is used

.changeset/old-dogs-sin.md

@@ -0,0 +1,8 @@
+---
+"@sit-onyx/nuxt": major
+"docs": patch
+---
+
+Require mapping of onyx locales to the project ones.
+
+This change was necessary because registering all languages supported by onyx would force the project to also support them due to the way locales are merged by nuxt-i18n.

apps/docs/src/development/packages/nuxt.md

@@ -45,12 +45,32 @@ If your Nuxt project uses both modules, onyx will automatically detect it and us
 
 ### Setup
 
-The setup is automated, @sit-onyx/nuxt will check if @nuxtjs/i18n is registered as well and register all onyx translations and add a plugin to handle the translations for onyx using vue-i18n.
+To merge the locales provided by onyx with your own, you need to define a mapping.
+
+```ts [nuxt.config.ts]
+export default defineNuxtConfig({
+  modules: ["@sit-onyx/nuxt", "@nuxtjs/i18n"],
+  i18n: {
+    defaultLocale: "en_US",
+    langDir: "./i18n",
+    locales: [
+      { code: "en_US", file: "en-US.json", name: "English (US)" },
+      { code: "de", file: "de-DE.json", name: "Deutsch" },
+    ],
+  },
+  onyx: {
+    i18n: {
+      registerLocales: {
+        "de-DE": "de-DE",
+        en_US: "en-US",
+      },
+    },
+  },
+});
+```
 
 > Please register @sit-onyx/nuxt **before** @nuxtjs/i18n. Otherwise the translations for onyx won't be picked up by @nuxtjs/i18n.
 
-If your project uses standard language codes in the [BCP 47](https://www.rfc-editor.org/info/bcp47) format, supported translations will automatically be mapped correctly. Otherwise you'll have to define the mapping yourself by importing the messages inside your projects language definition. (See: [Extending onyx translations](#extending-onyx-translations))
-
 ### Customizing onyx translations
 
 It might happen that a certain translation provided by onyx doesn't fit your project. As project specific translations will always overwrite the defaults from onyx, you can easily provide your own. Just define the key of the onyx translation inside your own messages scoped to the key "onyx". E.g. this example will remove the default brackets around the translation for "optional":

packages/nuxt/playground/nuxt.config.ts

@@ -16,4 +16,13 @@ export default defineNuxtConfig({
       { code: "int", iso: "de-DE", file: "int.ts", name: "International (DE)" },
     ],
   },
+  onyx: {
+    i18n: {
+      registerLocales: {
+        "en-US": "en-US",
+        "de-DE": "de-DE",
+        int: "de-DE",
+      },
+    },
+  },
 });

packages/nuxt/src/module.ts

@@ -14,6 +14,20 @@ export interface ModuleOptions {
    * @see https://onyx.schwarz/development/#installation
    */
   disableGlobalStyles?: boolean;
+  /**
+   * Settings related to the integration with @nuxtjs/i18n
+   */
+  i18n?: {
+    /**
+     * Mapping for registering the translations from onyx with @nuxtjs/i18n.
+     * @example
+     * ```ts
+     * registerLocales: { "en_US": "en-US" }
+     * ```
+     * This would register the onyx translations for the language "en-US" to the code "en_US" of your projects locales.
+     */
+    registerLocales?: Record<string, "en-US" | "de-DE" | "ko-KR">;
+  };
 }
 
 export default defineNuxtModule<ModuleOptions>({
@@ -57,7 +71,7 @@ export default defineNuxtModule<ModuleOptions>({
 
     // Quick check to warn the user as the @nuxtjs/i18n module needs to be registered after onyx for the default translations to work
     const onyxModuleIndex = getModuleIndex(nuxt.options.modules, "@sit-onyx/nuxt");
-    if (onyxModuleIndex > i18nModuleIndex) {
+    if (i18nModuleIndex >= 0 && onyxModuleIndex > i18nModuleIndex) {
       logger.warn(
         "The @nuxtjs/i18n module was registered before the @sit-onyx/nuxt module. The default translations of onyx won't be loaded, please register the @sit-onyx/nuxt module before @nuxtjs/i18n",
       );
@@ -68,13 +82,12 @@ export default defineNuxtModule<ModuleOptions>({
       const registerOnyxLocales: NuxtI18nModuleHooks["i18n:registerModule"] = (register) => {
         register({
           langDir: resolve("./runtime/locales"),
-          locales: [
-            // we need to use .js files instead of .ts because the .ts files would be compiled to .js in the build step, so
-            // when projects use this nuxt module, .ts files will throw a "can not find file" error
-            { code: "de-DE", file: "de-DE.js" },
-            { code: "en-US", file: "en-US.js" },
-            { code: "ko-KR", file: "ko-KR.js" },
-          ],
+          // we need to use .js files instead of .ts because the .ts files would be compiled to .js in the build step, so
+          // when projects use this nuxt module, .ts files will throw a "can not find file" error
+          locales: Object.entries(options.i18n?.registerLocales ?? {}).map(([code, language]) => ({
+            code,
+            file: `${language}.js`,
+          })),
         });
       };
 

packages/nuxt/test/fixtures/i18n/nuxt.config.ts

@@ -25,4 +25,13 @@ export default defineNuxtConfig({
       },
     ],
   },
+  onyx: {
+    i18n: {
+      registerLocales: {
+        "en-US": "en-US",
+        "de-DE": "de-DE",
+        int: "de-DE",
+      },
+    },
+  },
 });