@gluhar/i18n

Gluhar i18n (internationalization) package. Configures vue-i18n under the hood. Providers composables such as useMessages and SEO utils.

Most strong key point for this package is that I override the t function, so that it properly types the MessageKeys provided.

✨  Release Notes

Installation

Install the module to your Nuxt application with one command:

npx nuxi module add @gluhar/i18n

Define i18n Config

In your /config folder, create a i18n.config.ts file that is meant to both provide for @gluhar/i18n and the behind-the-scenes vueI18n.

Keep in mind to add as const on the two arrays for proper typing capabilities.

export const locales = [
  { code: "bg", iso: "bg-BG", name: "Български", abbr: "bg" },
  { code: "en", iso: "en-UK", name: "English", abbr: "en" },
] as const;
export const defaultLocale = "bg";
export const messageKeys = ["opa", "notFound"] as const;

// VueI18n Config Export
export default {
  legacy: false,
  locale: defaultLocale,
  messages: {},
};

Config the locales if you need to add/remove. Change the defaultLocale if needed.

And then during development, just add keys in messageKeys. This will automatically add a field in Global/Translations in Sanity where you need to add the actual translation message.

My current stack uses Sanity for CMS which provides the translation records. Thus we pass messages as an empty object, as it will be populated by loadMessages later.

If you wish to use it without Sanity and just straight out vueI18n, then define the messages object properly and omit the messageKeys array.

Usage

The package mainly provides the useMessage composables and some useful types.

const { loadMessages, t, l } = useMessages();

// If you use Sanity, which is expected to be the default.
// in app.vue
const translationsQuery = groq`
  *[_id == "translations"][0]
`;
const { data } = await useSanityQueryT<{
  ...,
  translations: Translations;
}>(`{
  ...,
  "translations": ${translationsQuery},
}`);

await loadMessages(data.value.translations);

// In all components, composables and pages
const msg = t('someMgsKey'); // this is typed, will throw error if key is not in messageKeys array

// l function is meant to translate LocaleFields provided from Sanity
const name: string = l(project.name);
const desc: Block[] = l(project.description);

Import interfaces for localised fields.

import type {
  LocaleString,
  LocaleBlocks,
  Messages,
  Translations,
} from "@gluhar/i18n";

Use auto-imported types as LangCode and MessageKey

Configuring @gluhar/i18n

The package automatically detects and uses ./config/i18.config.ts file to configure itself.

If you want to change the file name or location, or file structure. Then you can access the config and provide the custom path and options.

// nuxt.module.ts
{
  modules: [ ..., "@gluhar/i18n" ],

  gluharI18n: {
    vueI18n: "./msgsConfig.ts",
    // other @nuxtjs/i18n config options
  }
}

Contribution

# Install dependencies
npm install

# Generate type stubs
npm run dev:prepare

# Develop with the playground
npm run dev

# Build the playground
npm run dev:build

# Run ESLint
npm run lint

# Run Vitest
npm run test
npm run test:watch

# Release new version
npm run release