@hd-translate/adapter-vanilla

原生 JS 适配层 — data-i18n 属性扫描绑定

基于 @hd-translate/core 提供无框架接入能力。扫描 DOM 上带 data-i18n 属性的元素，把翻译结果写入 textContent；切换语言时自动重扫整树。

特性

• 零依赖框架 — 任何原生 JS / 老项目 / 多页应用 / 服务端模板渲染后追加绑定均可
• 声明式绑定 — HTML 上写 data-i18n="ns:key" 与 data-i18n-params='{"name":"World"}'，无需写 JS 渲染逻辑
• 自动重渲染 — 内部监听 localeChange，切换语言后整树自动重新翻译
• 自定义属性名 — attrName / paramsAttrName 可换名，避免与现有属性冲突
• 销毁解绑 — 返回 destroy() 解绑监听并销毁 i18n 实例

安装

pnpm add @hd-translate/core @hd-translate/adapter-vanilla

快速开始

<p data-i18n="common:hello" data-i18n-params='{"name":"World"}'></p>
<p data-i18n="common:confirm"></p>

import { createVanillaI18n } from '@hd-translate/adapter-vanilla'

const { i18n, bind } = createVanillaI18n({
  appId: 'my-product',
  apiUrl: 'https://i18n.example.com/api/translations',
  locale: 'zh-CN',
  fetcherOptions: {
    timeout: 10000,
    retries: 2,
  },
  cache: {
    ttl: 24 * 60 * 60 * 1000,
    persistent: true,
    version: '1.0',
  },
})

// 初始翻译加载完成后绑定一次
i18n.on('loaded', () => bind(document.body))

API

createVanillaI18n(options): { i18n, bind, update, destroy }

创建原生 JS i18n 适配器。

VanillaI18nOptions

继承 I18nOptions，附加：

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | attrName | string | 'data-i18n' | 元素上声明翻译 key 的属性名 | | paramsAttrName | string | 'data-i18n-params' | 元素上声明插值参数的属性名（JSON 字符串） |

返回值

| 字段 | 类型 | 说明 | |------|------|------| | i18n | I18nInstance | core i18n 实例，可调 t / setLocale / loadNamespace 等 | | bind(root?) | (root: Element \| Document) => void | 扫描根节点下所有带 data-i18n 的元素并写入翻译，默认 document | | update(root?) | (root: Element \| Document) => void | bind 的别名，语义上更明确 | | destroy() | () => void | 解绑 localeChange 监听并销毁 i18n 实例 |

适配器内部已监听 localeChange 事件，切换语言时自动调用 update() 重扫整树。

用法

插值参数

data-i18n-params 是 JSON 字符串，会被 JSON.parse 后传给 t()：

<p data-i18n="common:hello" data-i18n-params='{"name":"World"}'></p>
<!-- 翻译成"你好，World" -->

切换语言

const { i18n } = createVanillaI18n({ /* ... */ })

await i18n.setLocale('en')
// localeChange 触发后整树自动重新翻译，无需手动调 bind

按需加载命名空间

await i18n.loadNamespace('order')
bind(document.body) // 新增了 order 命名空间的元素，手动重扫一次

局部重新绑定

bind(root) 接受任意根节点，便于局部刷新：

const fragment = document.createElement('div')
fragment.innerHTML = `
  <p data-i18n="order:empty_hint"></p>
  <p data-i18n="order:list_title"></p>
`
document.body.appendChild(fragment)
bind(fragment) // 只扫新增片段

自定义属性名

避免与现有属性冲突，或对接已有约定：

const adapter = createVanillaI18n({
  appId: 'my-product',
  apiUrl: '/api/translations',
  locale: 'zh-CN',
  attrName: 'data-t',           // <p data-t="common:hello"></p>
  paramsAttrName: 'data-t-params',
})

销毁

const { destroy } = createVanillaI18n({ /* ... */ })
// 页面卸载或单测结束时
destroy()

注意事项

• 首次加载 — loaded 事件由 core 在翻译数据就绪后发射，但适配器不会自动在首次 loaded 时调 bind。需要在 i18n.on('loaded', () => bind(document.body)) 中手动触发一次。
• localeChange 已自动处理 — 切换语言后整树自动重扫，无需手动调 bind。
• JSON.parse 严格 — data-i18n-params 必须是合法 JSON（双引号包裹键与字符串值），否则会抛错。
• textContent 写入 — 适配器把翻译结果直接写入元素 textContent，不会解析 HTML。需要富文本请自行扩展。

License

MIT