@composy/i18n-vue

@composy/i18n-vue

@composy/i18n-vue 是 @composy/i18n-core 的 Vue 3 适配层。它只负责把 core 中的国际化能力封装为 Vue 项目中可直接使用的插件、组合式 API、组件和指令，不重复实现 core 已有的翻译引擎与类型系统。

安装

pnpm add @composy/i18n-core @composy/i18n-vue vue

分层说明

• @composy/i18n-core

  • 提供框架无关的国际化核心能力
  • 负责翻译、缓存、格式化、复数规则、插件与调试工具

• @composy/i18n-vue

  • 只依赖 @composy/i18n-core 与 vue
  • 负责插件安装、Composition API、组件、指令与 Vue 场景的使用体验封装

快速开始

通过 setupI18n() 快速接入

import { setupI18n } from '@composy/i18n-vue'
import { createApp } from 'vue'
import App from './App.vue'

const app = createApp(App)

setupI18n(app, {
  locale: 'zh-CN',
  fallbackLocale: 'en-US',
  messages: {
    'zh-CN': { hello: '你好' },
    'en-US': { hello: 'Hello' },
  },
})

app.mount('#app')

通过 createI18nPlugin() 自行管理实例

import { createI18n, createI18nPlugin } from '@composy/i18n-vue'
import { createApp } from 'vue'
import App from './App.vue'

const i18n = createI18n({
  locale: 'zh-CN',
  messages: {
    'zh-CN': { hello: '你好' },
  },
})

const app = createApp(App)
app.use(createI18nPlugin(i18n))
app.mount('#app')

在组件中使用 useI18n()

<script setup lang="ts">
import { useI18n } from '@composy/i18n-vue'

const { t, locale, setLocale } = useI18n()
</script>

<template>
  <div>
    <h1>{{ t('hello') }}</h1>
    <button @click="setLocale('zh-CN')">
      中文
      <span v-if="locale === 'zh-CN'">（当前）</span>
    </button>
    <button @click="setLocale('en-US')">
      English
      <span v-if="locale === 'en-US'">（当前）</span>
    </button>
  </div>
</template>

主要能力

插件与实例

• createI18n()：创建 Vue 场景使用的 i18n 实例
• createI18nPlugin()：创建 Vue 插件
• LDesignI18nPlugin：类式安装入口
• setupI18n()：一步完成实例创建与插件安装

组合式 API

• useI18n()：主入口，提供翻译、格式化、语言管理、消息管理
• useLocale()：专注语言状态与切换
• useTranslation()：带命名空间的翻译入口
• useI18nScope()：组件级局部作用域封装
• useI18nFormat()、useI18nPlural()、useI18nAsync() 等辅助 Hook

useI18nAsync() 会自动取消上一轮加载，并忽略不支持取消信号的旧加载器结果；组件销毁时也会停止其状态更新。多个语言包请求并发发生时，只有最新请求的错误和成功结果会写入组合式状态。

Vue 绑定严格归属于当前 App：多个 Vue 应用可以使用不同的 i18n 实例，不会通过模块级全局变量互相串扰。插件安装时写入的 $i18n、$t、$locale 和注入值，会在 App 卸载或 Engine 插件卸载时恢复此前值。

组件

• I18nProvider
• I18nText
• I18nTranslate
• I18nNumber
• I18nDatetime
• LanguageSwitcher

指令

• v-t
• v-t-html
• v-t-plural
• v-t-tooltip
• v-t-date
• v-t-number

与 @composy/engine-core 集成

当项目同时使用 @composy/engine-core 时，可通过 createI18nEnginePlugin() 把 core 层 engine plugin 与 Vue 安装流程连接起来，避免应用层重复做实例注入和安装逻辑。

工具函数

• defineI18nConfig()：定义类型安全的配置对象
• loadLocaleMessages()：统一加载动态语言包

开发命令

pnpm build
pnpm type-check
pnpm lint:check
pnpm test

注意事项

• 当前包是 Vue 3 适配层，不应承载框架无关的核心逻辑。
• 如果需要扩展翻译算法、缓存、插件协议或类型定义，应优先修改 @composy/i18n-core。
• 当前 pnpm type-check 使用本地专用配置 .ldesign/tsconfig.typecheck.json，直接校验 @composy/i18n-core 源码而不依赖预构建声明。
• TypeScript、ESLint 与 @composy/builder 的权威配置位于本包 .ldesign/；根目录同名配置保留为兼容入口。

许可证

createI18nEnginePlugin({
  installVuePlugin: false,
  locale: 'en',
  messages: {
    en: { hello: 'Hello' },
  },
})

目录结构

src/
├── components/
│   ├── I18nText.tsx
│   ├── I18nNumber.tsx
│   ├── I18nDatetime.tsx
│   ├── I18nProvider.tsx
│   └── LanguageSwitcher.tsx
├── composables/
│   ├── useI18n.ts
│   ├── useLocale.ts
│   └── ...
├── core/
│   ├── constants.ts
│   ├── plugin-options.ts
│   └── types.ts
├── directives/
│   ├── vT.ts
│   ├── vTHtml.ts
│   ├── vTPlural.ts
│   └── ...
├── plugins/
│   ├── createI18nPlugin.ts
│   ├── createI18nEnginePlugin.ts
│   └── installVueI18n.ts
├── utils/
│   ├── createI18n.ts
│   ├── defineI18nConfig.ts
│   ├── loadLocaleMessages.ts
│   └── setupI18n.ts
└── index.ts

职责约束：

• core/ 只放 Vue 适配层共享类型、注入键和配置模型
• plugins/ 只放安装入口和 bridge，不承载业务逻辑
• utils/ 只放实例创建、配置声明和加载辅助函数
• components/、directives/、composables/ 只放 Vue 表层能力

API 概览

• createI18n(config)：创建并初始化 i18n 实例
• createI18nPlugin(i18n, options)：原生 Vue Plugin 安装入口
• createI18nEnginePlugin(options)：@composy/engine-core bridge 入口
• setupI18n(app, config, pluginOptions?)：快速创建并安装
• useI18n() / useLocale() / useTranslation()：组合式 API

说明

• localeSwitcher 配置通过统一的 Vue 安装内核提供给 LanguageSwitcher
• 原生 Vue Plugin 与 engine plugin 最终都会走 installVueI18n(...)
• packages/vue 不再声明不存在的全局 CSS 产物，组件样式由组件自身显式引入
• createI18nEnginePlugin() 在 Engine 卸载前会解除仍存活的 Vue App 绑定，避免 App 继续访问已销毁实例

License

MIT