@gluhar/i18n
Gluhar i18n package. Installs and configures @nuxtjs/i18n from one project file, and provides useMessages with typed message keys.
How i18n works in a gluhar project
There are two kinds of text, and they never mix:
| Where it lives | Read with | |
|---|---|---|
| UI strings (buttons, labels, errors) | lang/<code>.json, shipped with the build | t("key") |
| Content (anything an editor writes) | Sanity, localised per field (localeString, localeText, localeBlock) | l(field) |
UI strings are NOT authored in Sanity. A Studio document that mirrors lang/*.json is a second source of truth and the two drift — v6 removed loadMessages and the Translations type for that reason.
Config — config/i18n.config.ts
The single source of truth for locales. The Studio imports it too, so keep it a plain static module.
export const locales = [
{ code: "bg", language: "bg-BG", name: "Български" },
{ code: "en", language: "en-GB", name: "English" },
] as const;
export const defaultLocale = "bg";
// Optional. Locale t() falls back to for a missing key. Default: defaultLocale.
export const fallbackLocale = "en";
as const is required: LangCode is typed from it. Never write a locale code anywhere else (route rules, sitemap excludes, redirects) — derive it from locales / defaultLocale. Which locale is the default changes more often than you'd think.
Messages go in lang/<code>.json (nested keys are fine). Keys are typed from the default locale's file, so t("missing.key") is a type error.
Defaults
strategy: "prefix_except_default"— the default locale is unprefixed, every other one is/<code>/….detectBrowserLanguage: false— a cookie-driven 302 on/can't work with ISR-cached HTML and contradicts hreflang. The language picker is the switch.fallbackLocaleis applied through a generated vue-i18n config. To take over vue-i18n config entirely, addi18n/i18n.config.ts(defineI18nConfig); it wins over the generated one.
The resolved options are written to nuxt.options.i18n, so modules that read i18n config back (@nuxtjs/sitemap, nuxt-seo) see the real locales. Do not mirror the config in a top-level i18n key — v5 projects did that as a workaround; on v6 it duplicates every locale. Other @nuxtjs/i18n options (e.g. baseUrl) go in gluhar.i18n or a top-level i18n key — just not locales.
Usage
const { t, l, locale } = useMessages();
t("form.submit"); // typed key from lang/<default>.json
t("plan.symmetric", { speed: 500 }); // fills "[speed]"; unfilled [x] are removed
l(page.title); // { bg, en } → the active locale's value
l() has no fallback: a field filled in only one language renders empty in the other.
Types: LocaleString, LocaleBlocks, LocaleField<V> (importable from @gluhar/i18n/types and global), plus the generated globals LangCode and MessageKey.
Contribution
Local development
# 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