vtj/docs/llms/i18n.md

VTJ 国际化（i18n）— AI 配置与使用指南

本文档帮助 AI 理解如何通过工具方法配置国际化词条，以及在组件中实现多语言文本。

---

一、数据流全貌

设计器 i18n 面板                    项目数据                         渲染引擎
i18n/index.vue  ──setI18n()──▶  project.i18n  ──initI18n()──▶  VueI18n 插件注册
  (表格编辑)                      (I18nConfig)   (消息格式转换)    (app.use)
                                                    │
                                [ { key, 'zh-CN', en } ] →  { 'zh-CN': { key: value }, en: { key: value } }

关键流程：

1. 词条存储： 设计器以扁平数组形式存储 [{ key, 'zh-CN', en }]
2. 渲染器转换： initI18n() 将扁平数组转为 locale 分组的嵌套对象 { 'zh-CN': { key: value }, en: { key: value } }
3. 插件注册： 通过 VueI18n.createI18n() 创建 vue-i18n 实例，以 Composable API 模式（legacy: false）注册到 Vue 应用
4. 全局可用： 组件中通过 __i18n 访问翻译功能，模板和 script 均使用 __i18n.t('key')

---

二、I18n 工具方法

getI18nMessage — 获取所有词条

获取当前项目已配置的全部中英对照词条。

参数： 无

返回： I18nMessage[] 数组，每项包含 key、zh-CN、en

---

createI18nMessage — 新增词条

新增一条中英文对照词条。key 必须唯一，重复的 key 会覆盖。

参数：

参数	类型	必填	说明
message.key	string	✅	词条标识，推荐点号分层命名，如 common.confirm、user.profile.name
message.zh-CN	string	✅	简体中文内容
message.en	string	✅	英文内容

示例：

{
  "action": "createI18nMessage",
  "parameters": [
    {
      "key": "common.submit",
      "zh-CN": "提交",
      "en": "Submit"
    }
  ]
}

批量创建词条： 需要多次调用此工具，每次传入一条。

---

removeI18nMessage — 删除词条

通过 key 删除指定词条。

参数：

• key: string — 词条标识

示例：

{
  "action": "removeI18nMessage",
  "parameters": ["common.submit"]
}

---

三、语言设置（locale / fallbackLocale）

国际化有两个全局设置：

设置项	键名	可选值	说明
默认语言	locale	zh-CN / en	应用启动时使用的语言
回退语言	fallbackLocale	zh-CN / en	找不到翻译时的兜底语言

⚠️ 暂无对应工具方法。 当前 locale 和 fallbackLocale 只能通过设计器 i18n 面板的「设置」按钮手动配置，无对应的 AI 工具调用。如未配置，默认均为 zh-CN。

运行时切换语言

__i18n 是 useI18n() 返回的 Composable 实例，其 locale 属性，运行时直接修改即可切换语言：

模板中切换（如点击按钮）：

<template>
  <div>
    <p>{{ __i18n.t('page.greeting') }}</p>

    <!-- 切换到中文 -->
    <el-button @click="__i18n.locale = 'zh-CN'"> 中文 </el-button>

    <!-- 切换到英文 -->
    <el-button @click="__i18n.locale = 'en'"> English </el-button>
  </div>
</template>

script 中切换：

// 切换到英文
__i18n.locale = 'en';

// 切换到中文
__i18n.locale = 'zh-CN';

// 读取当前语言
console.log(__i18n.locale); // 'zh-CN' 或 'en'

完整场景示例 — 带下拉菜单的语言切换：

<template>
  <div class="header">
    <h1>{{ __i18n.t('app.title') }}</h1>

    <el-dropdown @command="handleSwitchLang">
      <el-button>
        {{ currentLangLabel }}
        <el-icon><ArrowDown /></el-icon>
      </el-button>
      <template #dropdown>
        <el-dropdown-menu>
          <el-dropdown-item command="zh-CN">🇨🇳 中文</el-dropdown-item>
          <el-dropdown-item command="en">🇺🇸 English</el-dropdown-item>
        </el-dropdown-menu>
      </template>
    </el-dropdown>
  </div>
</template>

<script setup>
  import { computed } from 'vue';

  const currentLangLabel = computed(() => {
    return __i18n.locale === 'en' ? 'English' : '中文';
  });

  function handleSwitchLang(locale) {
    __i18n.locale = locale;
  }
</script>

💡 切换 locale 后，所有使用 __i18n.t() 的文本会自动更新为对应语言的翻译，无需手动刷新页面。

---

四、组件中使用国际化

4.1 模板中使用（推荐方式）

VTJ 使用 vue-i18n Composition API 模式（legacy: false），模板中必须使用 __i18n.t()，不支持 Options API 的 $t()。

<template>
  <div>
    <h1>{{ __i18n.t('page.dashboard.title') }}</h1>
    <el-button>{{ __i18n.t('common.submit') }}</el-button>
    <el-table :empty-text="__i18n.t('table.empty')">
      <!-- ... -->
    </el-table>
  </div>
</template>

4.2 script 中使用

在 <script setup> 中通过 __i18n 全局变量访问：

// 文本翻译
const title = __i18n.t('page.dashboard.title');
const confirmText = __i18n.t('common.confirm');

// 带插值参数
const message = __i18n.t('user.welcome', { name: '张三' });

// 数字格式化
const formatted = __i18n.n(1234567, 'currency');
// 等价于模板中: {{ __i18n.n(1234567, 'currency') }}

// 日期格式化
const dateStr = __i18n.d(new Date(), 'short');
// 等价于模板中: {{ __i18n.d(new Date(), 'short') }}

4.3 Vue SFC 完整示例

<template>
  <div class="user-profile">
    <h1>{{ __i18n.t('user.profile.title') }}</h1>

    <el-descriptions :column="2" border>
      <el-descriptions-item :label="__i18n.t('user.profile.name')">
        {{ __state.user?.name }}
      </el-descriptions-item>
      <el-descriptions-item :label="__i18n.t('user.profile.email')">
        {{ __state.user?.email }}
      </el-descriptions-item>
      <el-descriptions-item :label="__i18n.t('user.profile.phone')">
        {{ __state.user?.phone }}
      </el-descriptions-item>
    </el-descriptions>

    <div class="footer">
      <el-button @click="__state.onBack">
        {{ __i18n.t('common.back') }}
      </el-button>
      <el-button type="primary" @click="__state.onEdit">
        {{ __i18n.t('user.profile.edit') }}
      </el-button>
    </div>
  </div>
</template>

<script setup>
  import { reactive } from 'vue';

  const __state = reactive({
    user: {
      name: '',
      email: '',
      phone: ''
    },
    onBack() {
      __router.back();
    },
    onEdit() {
      // 编辑逻辑
    }
  });

  onMounted(async () => {
    const res = await __apis['getUserInfo']();
    __state.user = res.data?.data || {};
  });
</script>

---

五、词条 Key 命名规范

推荐使用点号分层的命名方式，按「模块.页面.元素」的结构组织：

规范	示例 Key	中文值	说明
通用类	common.submit	提交	跨页面复用的通用文案
	common.cancel	取消
	common.confirm	确认
	common.delete	删除
	common.back	返回
表格类	table.empty	暂无数据	表格空状态
	table.search	查询
	table.reset	重置
业务页面	user.list.title	用户列表	特定页面的标题
	user.list.create	新增用户
	user.profile.name	姓名	用户详情字段
	order.detail.status	状态	订单状态标签
表单校验	validation.required	此项必填	表单校验提示
	validation.email	邮箱格式不正确
操作提示	tips.deleteConfirm	确定删除该项？	操作前的确认提示
	tips.saveSuccess	保存成功
	tips.saveFailed	保存失败，请重试

---

六、典型工作流程

6.1 新建项目时的 i18n 配置流程

1. 分析页面中的静态文案，整理成词条清单
2. 逐条调用 createI18nMessage 创建词条
3. 在 Vue 模板中使用 __i18n.t('key') 替代硬编码文本

6.2 新增页面时

1. 查看现有词条：getI18nMessage
2. 复用已有词条（如 common.*）
3. 创建新词条：createI18nMessage
4. 在生成的 Vue 代码中使用 __i18n.t('key')

---

七、带插值参数的翻译

词条中可以包含 {name} 占位符，调用时传入参数：

{
  "action": "createI18nMessage",
  "parameters": [
    {
      "key": "user.welcome",
      "zh-CN": "欢迎回来，{name}！",
      "en": "Welcome back, {name}!"
    }
  ]
}

模板中使用：

<span>{{ __i18n.t('user.welcome', { name: __state.userName }) }}</span>

Script 中使用：

const msg = __i18n.t('user.welcome', { name: __state.userName });

---

八、注意事项

1. key 必须唯一： 重复的 key 会导致词条覆盖，创建前可通过 getI18nMessage 确认
2. zh-CN 和 en 均必须填写： 每条词条的中英文内容均不可为空
3. 统一使用 __i18n.t()： VTJ 使用 Composition API 模式（legacy: false），模板和 script 中均使用 __i18n.t('key')，不支持 Options API 的 $t() 写法
4. 不需要手动 import： __i18n 是由 vue-i18n 的 useI18n() 提供的全局变量，框架已自动注入，组件中无需手动导入
5. 设置后需 refresh 生效： 通过工具新增词条后，需要调用 refresh 刷新运行时才能看到效果
6. locale/fallbackLocale 无工具： 默认语言和回退语言需通过设计器面板手动配置