@hd-translate/adapter-vue3

Vue 3 适配层 — plugin / useI18n / v-t 指令

基于 @hd-translate/core 提供 Vue 3 应用接入能力：一行 app.use() 完成实例注入、指令注册与全局属性挂载，组件内通过 useI18n() 拿到响应式的 t / locale / setLocale。

特性

• Composition API — useI18n() 返回的 t 与 locale 均为响应式，翻译异步加载完成后自动重渲染
• v-t 指令 — 模板里直接 v-t="'ns:key'" 或 v-t="{ key, params }"，无需额外插值
• 全局属性 — 默认挂 $t / $i18n，属性名可配置
• 跨应用单例 — I18N_INJECTION_KEY 使用 Symbol.for，多 Vue 应用共享同一实例
• SSR 友好 — 插件返回值携带 .i18n，便于在 SSR / 单测中直接拿到实例

安装

pnpm add @hd-translate/core @hd-translate/adapter-vue3 vue@^3

快速开始

// main.js
import { createApp } from 'vue'
import { createI18nPlugin } from '@hd-translate/adapter-vue3'
import App from './App.vue'

const i18nPlugin = createI18nPlugin({
  appId: 'my-product',
  apiUrl: 'https://i18n.example.com/api/translations',
  locale: 'zh-CN',
  fallbackLocale: 'en',
  namespaces: ['common', 'menu'],
  fetcherOptions: {
    timeout: 10000,
    retries: 2,
    headers: { 'X-App-Version': '1.0.0' },
  },
  cache: {
    ttl: 24 * 60 * 60 * 1000,
    persistent: true,
    version: '1.0',
  },
})

createApp(App).use(i18nPlugin).mount('#app')

<!-- App.vue -->
<script setup>
import { useI18n } from '@hd-translate/adapter-vue3'
const { t, locale, setLocale } = useI18n()
</script>

<template>
  <p>{{ t('common:hello', { name: 'Vue' }) }}</p>
  <p v-t="'common:confirm'"></p>
  <p v-t="{ key: 'common:hello', params: { name: 'Directive' } }"></p>
  <button @click="setLocale('en')">English</button>
  <button @click="setLocale('zh-CN')">中文</button>
</template>

API

createI18nPlugin(options): Plugin & { i18n: I18nInstance }

创建 Vue 3 插件。install 时完成：

1. app.provide(I18N_INJECTION_KEY, i18n) — 注入实例供 useI18n() 通过 inject 取用
2. app.directive('t', createVDirective(i18n)) — 注册 v-t 指令
3. app.config.globalProperties[globalName] = i18n.t 与 $i18n = i18n — 挂全局属性

返回值既是 Plugin 又携带 .i18n 实例，便于 SSR / 单测直接拿到。

VueI18nOptions

继承 I18nOptions，附加：

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | global | boolean | - | 预留字段，便于未来扩展全局模式 | | globalPropertyName | string | '$t' | 挂到 globalProperties 上的翻译函数名 |

useI18n(): UseI18nReturn

在组件 setup 中获取 i18n 能力。必须在已 install 插件的应用内调用，否则抛错。

内部维护两个 ref：

• locale — 当前语言，监听 localeChange 同步更新
• revision — 翻译数据加载完成（loaded 事件）时递增；t 内部读取它建立 Vue 响应式依赖，确保翻译异步到达后组件重渲染

监听器在 onUnmounted 自动解绑。

UseI18nReturn

| 字段 | 类型 | 说明 | |------|------|------| | t | (key, params?) => string | 翻译函数，响应式依赖 revision | | locale | Ref<string> | 当前语言 | | setLocale | (locale) => Promise<void> | 切换语言 | | loadNamespace | (ns) => Promise<void> | 按需加载命名空间 |

createVDirective(i18n): Directive<HTMLElement>

创建 v-t 指令。指令值支持两种形式：

<!-- 字符串 -->
<p v-t="'common:hello'"></p>

<!-- 对象（带插值参数） -->
<p v-t="{ key: 'common:hello', params: { name: 'Vue' } }"></p>

mounted / updated 钩子里把翻译结果写入元素 textContent。

I18N_INJECTION_KEY

Symbol.for('hd-translate')，跨 Vue 应用单例。需要手动 inject 时可用：

import { inject } from 'vue'
import { I18N_INJECTION_KEY } from '@hd-translate/adapter-vue3'

const i18n = inject(I18N_INJECTION_KEY)

进阶用法

Options API 中使用

v-t 指令与全局 $t 在 Options API 中同样可用：

<script>
export default {
  data() {
    return { name: 'Vue' }
  },
}
</script>

<template>
  <p>{{ $t('common:hello', { name }) }}</p>
  <p v-t="'common:confirm'"></p>
</template>

按需加载命名空间

import { useI18n } from '@hd-translate/adapter-vue3'

const { loadNamespace, t } = useI18n()

async function enterOrdersPage() {
  await loadNamespace('order')
  console.log(t('order:list_title'))
}

自定义全局属性名

const i18nPlugin = createI18nPlugin({
  // ...
  globalPropertyName: '$translate',  // 模板内用 $translate('common:hello')
})

SSR / 单测中直接拿到实例

import { createI18nPlugin } from '@hd-translate/adapter-vue3'

const plugin = createI18nPlugin({ /* options */ })
// plugin.i18n 即 createI18n 返回的实例
await new Promise(resolve => plugin.i18n.on('loaded', resolve))
console.log(plugin.i18n.t('common:hello'))

License

MIT