@yiiamee/multilinguist 1.2.8 → 1.3.1

package/README.md

@@ -1,6 +1,7 @@
-# Nuxt MultiLinguist module
+# Nuxt Multilinguist module
 
-Multilinguist is a simple but smoothly working module for easy and seamless localization implementation for Nuxt applications. 
+Multilinguist is a simple but smoothly working module for easy and seamless localization implementation for Nuxt
+applications.
 
 ## Key Features
 
@@ -8,6 +9,7 @@ Multilinguist is a simple but smoothly working module for easy and seamless loca
 - Works perfectly fine on both SSR + CSR
 - No memory leaks and running out of memory errors
 - Autocompletion & validation of keys
+- Autodetection of browser's locale
 
 ## Installation
 
@@ -20,7 +22,7 @@ Then, add the module to your nuxt.config
 ```nuxt.config.ts
 export default defineNuxtConfig({
     modules: [
-        @yiiamee/multilinguist,
+        "@yiiamee/multilinguist",
     ],
     multilinguist: {
         defaultLocale: "en", // string representing key to your default (fallback) locale
@@ -35,18 +37,65 @@ Then, create a "locales" directory in /public directory. This is necessary for m
 
 Now, you're ready to use Multilinguist Module!
 
+After running your project, you can see the following warning:
+
+![vite-warning.png](vite-warning.png)
+
+**Dont be scared**, this is just a message from the module, indicating that your locales are typed, and that the module
+can properly perform type-checks and autocompletion.
+
+Also, on both SSR and CSR, you will see the following message:
+
+![initialized.png](initialized.png)
+
+It indicated that the module has been initialized successfully.
+
+To disable logs, you can set the `logging` option in your nuxt.config to `false` (by default, it is `true`):
+
+```nuxt.config.ts
+export default defineNuxtConfig({
+    modules: [
+        "@yiiamee/multilinguist",
+    ],
+    multilinguist: {
+        defaultLocale: "en",
+        supportedLanguages: ["en", "es"],
+        logging: false, // Boolean value to define if the module should send internal logs to console
+    },
+})
+```
+Also, Multilinguist offers a functionality to set the default browser's locale as default if it is available in the supported languages array.
+
+To disable this option, you can set the `setBrowserLanguage` option to `false` as it is `true` by default:
+
+```nuxt.config.ts
+export default defineNuxtConfig({
+    modules: [
+        "@yiiamee/multilinguist",
+    ],
+    multilinguist: {
+        defaultLocale: "en",
+        supportedLanguages: ["en", "es"],
+        logging: false,
+        setBrowserLanguage: false, // by default: true
+    },
+})
+```
+
+
 # Usage
 
-### t()—famous translate function 
- 
+### t()—famous translate function
+
 ```vue
+
 <script setup lang="ts">
-const { t } = useMultilinguist(); // Call useMultilinguist composable to get the translation function
-  
-const pageTitle = computed(() => {
-  return t("Hello, World");
-});
-</script> 
+  const { t } = useMultilinguist(); // Call useMultilinguist composable to get the translation function
+
+  const pageTitle = computed(() => {
+    return t("Hello, World");
+  });
+</script>
 
 <template>
   <h3>{{ pageTitle }}</h3>
@@ -55,9 +104,10 @@ const pageTitle = computed(() => {
 ```
 
 It also supports nested keys and dynamic keys with variables;
-you only need to pass the second argument, an object with used in the key variables: 
+you only need to pass the second argument, an object with used in the key variables:
 
 ```vue
+
 <template>
   <span>{{ t("Paste your variable here", { variable: locale }) }}</span>
 </template>
@@ -72,13 +122,14 @@ And your JSON must look like that:
 ```
 
 ```vue
+
 <script setup lang="ts">
-const { t } = useMultilinguist(); // Call useMultilinguist composable to get the translation function
-  
-const pageTitle = computed(() => {
-  return t("Hello, World");
-});
-</script> 
+  const { t } = useMultilinguist(); // Call useMultilinguist composable to get the translation function
+
+  const pageTitle = computed(() => {
+    return t("Hello, World");
+  });
+</script>
 
 <template>
   <h3>{{ pageTitle }}</h3>
@@ -101,15 +152,16 @@ And validation:
 ### Set another value to the current locale:
 
 ```vue
+
 <script setup lang="ts">
-const { t, setLocale } = useMultilinguist();
-// setLocale function accepts a string that should match one of defined
-// in the nuxt.config strings from supportedLanguages array
-  
-const pageTitle = computed(() => {
-  return t("Hello, World");
-});
-</script> 
+  const { t, setLocale } = useMultilinguist();
+  // setLocale function accepts a string that should match one of defined
+  // in the nuxt.config strings from supportedLanguages array
+
+  const pageTitle = computed(() => {
+    return t("Hello, World");
+  });
+</script>
 
 <template>
   <h3>{{ pageTitle }}</h3>
@@ -120,18 +172,45 @@ const pageTitle = computed(() => {
 ### Get current locale
 
 ```vue
+
+<script setup lang="ts">
+  const { t, setLocale, locale } = useMultilinguist();
+  // locale is SSR friendly, shared among the app ref state  
+
+  const pageTitle = computed(() => {
+    return t("Hello, World");
+  });
+</script>
+
+<template>
+  <h3>{{ pageTitle }}</h3>
+  <h6>Current Locale: {{ locale }}</h6>
+  <button @click="setLocale('es')">{{ t("Switch Locale") }}</button>
+</template>
+```
+
+### Get locales list
+
+```vue
+
 <script setup lang="ts">
-const { t, setLocale, locale } = useMultilinguist();
-// locale is SSR friendly, shared among the app ref state  
+  const { t, setLocale, locale, locales } = useMultilinguist();
+  // Locales is a computed ref, which value is being set from your nuxt.config
 
-const pageTitle = computed(() => {
+  const pageTitle = computed(() => {
     return t("Hello, World");
-});
+  });
 </script>
 
 <template>
   <h3>{{ pageTitle }}</h3>
   <h6>Current Locale: {{ locale }}</h6>
+  <span
+    v-for="localeItem from locales"
+    :key="localeItem"
+  >
+    | {{ localeItem }} |
+  </span>
   <button @click="setLocale('es')">{{ t("Switch Locale") }}</button>
 </template>
 ```

package/dist/module.json

@@ -1,10 +1,16 @@
 {
   "name": "@yiiamee/multilinguist",
   "configKey": "multilinguist",
-  "version": "1.2.8",
+  "version": "1.3.1",
   "compatibility": {
     "nuxt": "^3.0.0"
   },
+  "defaults": {
+    "logging": true,
+    "defaultLocale": "",
+    "supportedLanguages": [],
+    "setBrowserLanguage": true
+  },
   "builder": {
     "@nuxt/module-builder": "1.0.1",
     "unbuild": "3.5.0"

package/dist/module.mjs

@@ -49,7 +49,7 @@ declare module 'vue' {
 }
 `;
 };
-function GenerateLocaleKeysPlugin(defaultLocaleFromConfig, localesPath, outPath) {
+function GenerateLocaleKeysPlugin(defaultLocaleFromConfig, localesPath, outPath, logging = true) {
   async function generateTypes() {
     const defaultLocalePath = path.join(localesPath, `${defaultLocaleFromConfig}.json`);
     if (!fs.existsSync(defaultLocalePath)) {
@@ -61,7 +61,9 @@ function GenerateLocaleKeysPlugin(defaultLocaleFromConfig, localesPath, outPath)
     const output = generateOutputString(() => keys.map((key) => `  ${JSON.stringify(key)}: string;`).join("\n"));
     fs.mkdirSync(path.dirname(outPath), { recursive: true });
     fs.writeFileSync(outPath, output, "utf-8");
-    console?.warn(`\u2705 Generated types to ${outPath} from ${defaultLocalePath}`);
+    if (logging) {
+      console?.warn(`\u2705 Generated types to ${outPath} from ${defaultLocalePath}`);
+    }
   }
   return {
     name: "vite-plugin-generate-locales-types",
@@ -80,22 +82,35 @@ const module = defineNuxtModule({
   meta: {
     name: "@yiiamee/multilinguist",
     configKey: "multilinguist",
-    version: "1.2.8",
+    version: "1.3.1",
     compatibility: {
       nuxt: "^3.0.0"
+    },
+    defaults: {
+      logging: true,
+      defaultLocale: "",
+      supportedLanguages: [],
+      setBrowserLanguage: true
     }
   },
   setup(moduleOptions, nuxtApp) {
     const resolver = createResolver(import.meta.url);
     addPlugin(resolver.resolve("runtime/plugin"));
     addImportsDir(resolver.resolve("runtime/composables"));
+    nuxtApp.options.runtimeConfig.public.multilinguist = {
+      defaultLocale: moduleOptions.defaultLocale,
+      supportedLanguages: moduleOptions.supportedLanguages,
+      logging: typeof moduleOptions.logging === "boolean" ? moduleOptions.logging : true,
+      setBrowserLanguage: typeof moduleOptions.setBrowserLanguage === "boolean" ? moduleOptions.setBrowserLanguage : true
+    };
     nuxtApp.hook("vite:extendConfig", (viteConfig) => {
       viteConfig.plugins = viteConfig.plugins || [];
       viteConfig.plugins.push(
         GenerateLocaleKeysPlugin(
           moduleOptions.defaultLocale,
           `${nuxtApp.options.rootDir}/public/locales`,
-          resolver.resolve("./runtime/types/generated-locales.d.ts")
+          resolver.resolve("./runtime/types/generated-locales.d.ts"),
+          moduleOptions.logging
         )
       );
     });
@@ -104,10 +119,6 @@ const module = defineNuxtModule({
         path: resolver.resolve("./runtime/types/generated-locales.d.ts")
       });
     });
-    nuxtApp.options.runtimeConfig.public.multilinguist = {
-      defaultLocale: moduleOptions.defaultLocale,
-      supportedLanguages: moduleOptions.supportedLanguages
-    };
   }
 });
 

package/dist/runtime/composables/useLocalization.d.ts

@@ -1,4 +1,4 @@
-import { type Ref } from "vue";
+import { type Ref, type ComputedRef } from "vue";
 import type { LocaleKey } from "../types/generated-locales.js";
 export type TranslationMap = readonly string[];
 export type Locale<T extends TranslationMap> = T[number];
@@ -8,5 +8,6 @@ export type TMultilinguistResponse<T extends TranslationMap> = {
     setLocale: (locale: Locale<T>) => void;
     initLocalization: () => Promise<void>;
     locale: Ref<Locale<T>>;
+    locales: ComputedRef<T>;
 };
-export default function useLocalization<const T extends TranslationMap>(supportedLanguages: T, defaultLocale: Locale<T>): TMultilinguistResponse<T>;
+export default function useLocalization<const T extends TranslationMap>(supportedLanguages: T, defaultLocale: Locale<T>, setBrowserLanguage?: boolean): TMultilinguistResponse<T>;

package/dist/runtime/composables/useLocalization.js

@@ -1,10 +1,10 @@
 import useLocale from "../composables/useLocale.js";
 import { useCookie, useState } from "nuxt/app";
 import { computed, watch } from "vue";
-export default function useLocalization(supportedLanguages, defaultLocale) {
+export default function useLocalization(supportedLanguages, defaultLocale, setBrowserLanguage = true) {
   const { locale: userBrowserLocale } = useLocale(supportedLanguages, defaultLocale);
   const userSelectedLocale = useCookie("multilinguist-locale", {
-    default: () => supportedLanguages.includes(userBrowserLocale.value) ? userBrowserLocale.value : defaultLocale
+    default: () => supportedLanguages.includes(userBrowserLocale.value) && setBrowserLanguage ? userBrowserLocale.value : defaultLocale
   });
   const localeFiles = import.meta.glob("@/public/locales/*.json", { eager: true });
   const loadedLanguages = useState("loaded-languages", () => ({}));
@@ -50,6 +50,9 @@ export default function useLocalization(supportedLanguages, defaultLocale) {
     await loadLocaleMessages(defaultLocale);
     await setLocale(userPrefferableLocale.value);
   };
+  const locales = computed(() => {
+    return supportedLanguages;
+  });
   watch(
     () => locale.value,
     async (val) => {
@@ -62,6 +65,7 @@ export default function useLocalization(supportedLanguages, defaultLocale) {
     t,
     setLocale,
     initLocalization,
-    locale
+    locale,
+    locales
   };
 }

package/dist/runtime/composables/useMultilinguist.d.ts

@@ -1,6 +1,8 @@
+import type { TranslationMap } from "./useLocalization.js";
 export default function useMultilinguist(): {
-    t<K extends LocaleKey>(key: K, variables?: Record<string, string>): string;
+    t<K extends import("../types/generated-locales.js").LocaleKey>(key: K, variables?: Record<string, string>): string;
     setLocale: (locale: string) => void;
     initLocalization: () => Promise<void>;
     locale: import("vue").Ref<string, string>;
+    locales: import("vue").ComputedRef<TranslationMap>;
 };

package/dist/runtime/plugin.js

@@ -3,13 +3,22 @@ import useLocalization from "../runtime/composables/useLocalization";
 export default defineNuxtPlugin(async (nuxtApp) => {
   const config = nuxtApp.$config.public.multilinguist || {
     defaultLocale: "en",
-    supportedLanguages: ["en"]
+    supportedLanguages: ["en"],
+    logging: true,
+    setBrowserLanguage: true
   };
   const supportedLanguages = config.supportedLanguages;
   const defaultLocale = config.defaultLocale;
-  const { initLocalization, ...localizationProperties } = useLocalization(supportedLanguages, defaultLocale);
+  const shouldSetBrowserLanguage = config.setBrowserLanguage;
+  const { initLocalization, ...localizationProperties } = useLocalization(
+    supportedLanguages,
+    defaultLocale,
+    shouldSetBrowserLanguage
+  );
   await initLocalization();
-  console.log("[multilinguist] is initialised");
+  if (nuxtApp.$config.public.multilinguist.logging) {
+    console.log("[multilinguist] is initialised");
+  }
   nuxtApp.provide("localization", localizationProperties);
   nuxtApp.provide("t", localizationProperties.t);
   nuxtApp._localization = localizationProperties;

package/dist/runtime/types/generated-locales.d.ts

@@ -0,0 +1,40 @@
+
+// AUTO-GENERATED FILE — DO NOT EDIT MANUALLY
+
+export interface TranslationMessages {
+  "Hello, World": string;
+  "Switch Locale": string;
+  "Paste your variable here": string;
+  "nested.Nested key": string;
+  "nested.Language": string;
+  "nested.nested second level.nested second level language": string;
+}
+
+export type LocaleKey = keyof TranslationMessages;
+
+export type TFunction = <K extends LocaleKey>(
+  key: K,
+  variables?: Record<string, string>
+) => string;
+
+declare global {
+  type LocaleKey = keyof TranslationMessages;
+  type TFunction = <K extends LocaleKey>(
+    key: K,
+    variables?: Record<string, string>
+  ) => string;
+}
+
+declare module '#app' {
+  interface NuxtApp {
+    $t: TFunction;
+    t: TFunction;
+  }
+}
+
+declare module 'vue' {
+  interface ComponentCustomProperties {
+    $t: TFunction;
+    t: TFunction;
+  }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@yiiamee/multilinguist",
-  "version": "1.2.8",
-  "description": "Nuxt 3 Multilinguist Localization module",
+  "version": "1.3.1",
+  "description": "Nuxt Multilinguist module for localizations",
   "repository": "yiiameeMich/multilinguist",
   "license": "MIT",
   "type": "module",
@@ -27,7 +27,10 @@
     "translation",
     "localization nuxt",
     "translation nuxt",
-    "nuxt translation"
+    "nuxt translation",
+    "nuxt multilinguist",
+    "multilinguist nuxt",
+    "ssr localization"
   ],
   "bugs": {
     "email": "michaelkukh.dev@gmail.com"