@gluhar/i18n

中文文档
6.4.1发布于 2026/11/16MITTypeScriptES Module近 30 天下载 3100

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

原始使用文档
文档目录5 节
  1. How i18n works in a gluhar project
  2. Config — config/i18n.config.ts
  3. Defaults
  4. Usage
  5. Contribution

@gluhar/i18n

npm version npm downloads License Nuxt

Gluhar i18n package. Installs and configures @nuxtjs/i18n from one project file, and provides useMessages with typed message keys.

✨  Release Notes

How i18n works in a gluhar project

There are two kinds of text, and they never mix:

Where it livesRead with
UI strings (buttons, labels, errors)lang/<code>.json, shipped with the buildt("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.
  • fallbackLocale is applied through a generated vue-i18n config. To take over vue-i18n config entirely, add i18n/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

版本与发布记录

@gluhar/i18n 共发布 37 个版本,首次发布于 2025/01/22;过去 12 个月发布了 26 个版本。

版本发布日期距今
6.4.1latest2026/11/16今天
6.4.02026/11/161 天前
6.3.22026/11/161 天前
6.3.12026/11/151 天前
6.3.02026/11/151 天前
6.2.02026/11/151 天前

其他发布通道:dev → 3.0.1-dev.2,next → 6.0.0-next.12。

关于 @gluhar/i18n 的常见问题

@gluhar/i18n 是什么?

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

如何安装 @gluhar/i18n?

在项目目录运行 npm install @gluhar/i18n,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:nuxt(^4.6.2)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@gluhar/i18n 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@gluhar/i18n 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@gluhar/i18n 可以商用吗?

@gluhar/i18n 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@gluhar/i18n 的下载量有多少?

根据 npm 官方下载统计,@gluhar/i18n 在 2026/10/17 – 2026/11/15 这 30 天内被下载 3,100 次,日均约 103 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@gluhar/i18n 还在维护吗?

最新版本 6.4.1 发布于 2026/11/16(今天);至今共发布 37 个版本,其中过去 12 个月发布了 26 个;首次发布于 2025/01/22。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。