ContextQMD
Back to Astron Rpa

项目国际化 (i18n) 操作文档

frontend/docs/I18n.md

1.1.67.9 KB
Original Source

项目国际化 (i18n) 操作文档

概述

本项目使用 @lobehub/i18n-cli 工具和 i18next 库实现国际化功能，支持中文（zh-CN）和英文（en-US）两种语言。

目录结构

locales/
├── package.json       # 语言包配置
├── zh-CN.json        # 中文语言包（主语言包）
└── en-US.json        # 英文语言包（自动翻译生成）

配置文件

1. .i18nrc.cjs - i18n 工具配置

javascript
const { env } = require('node:process')

const { defineConfig } = require('@lobehub/i18n-cli')

const modelName = env.OPENAI_MODEL_NAME || 'azure/gpt-4o-mini'

module.exports = defineConfig({
  modelName, // AI 翻译模型
  entry: 'locales/zh-CN.json', // 源语言文件
  entryLocale: 'zh-CN', // 源语言
  output: 'locales', // 输出目录
  outputLocales: ['en-US'], // 目标语言
  saveImmediately: true, // 每个翻译块完成后立即保存
  concurrency: 5, // 并发翻译数量
  temperature: 0.3, // AI 翻译温度参数
})

2. locales/package.json - 语言包模块配置

json
{
  "name": "@rpa/locales",
  "private": true,
  "version": "1.0.0",
  "exports": {
    "./zh-CN.json": "./zh-CN.json",
    "./en-US.json": "./en-US.json"
  }
}

项目实现方案

1. 语言包加载 (packages/web-app/src/config/i18n.ts)

typescript
import enUS from '@rpa/locales/en-US.json'
import zhCN from '@rpa/locales/zh-CN.json'

const locales = {
  'en-US': {
    lng: 'en-US',
    lang: 'English',
    value: enUS,
  },
  'zh-CN': {
    lng: 'zh-CN',
    lang: '简体中文',
    value: zhCN,
  },
}

export default locales

2. i18next 初始化 (packages/web-app/src/plugins/i18next.ts)

typescript
import i18next from 'i18next'

// 语言检测：优先使用中文，其他情况使用英文
const language = navigator.language === 'zh-CN' ? 'zh-CN' : 'en-US'

i18next.init({
  debug: false,
  lng: language,
  resources: {
    [language]: {
      translation: locales[language].value,
    },
  },
  interpolation: {
    escapeValue: false,
  },
})

// 翻译函数
export function translate(str: string | languageType, variables?: Record<string, string>): string {
  // 支持字符串插值，如: t('tableTotal', { count: 10 })
}

// 语言切换
export async function changeLanguage(lang: string) {
  i18next.addResourceBundle(lang, 'translation', locales[lang].value)
  await i18next.changeLanguage(lang)
}

3. Vue 组件中的使用

项目中主要有两种使用方式：

  1. 使用 useTranslation hook（推荐用法）
  2. 直接导入特定函数（如语言切换功能）

模板中使用：

vue
<template>
  <!-- 基础翻译 -->
  <div>{{ $t('projectName') }}</div>

  <!-- 带参数的翻译 -->
  <div>{{ $t('tableTotal', { count: 10 }) }}</div>

  <!-- 在属性中使用 -->
  <a-input :placeholder="$t('enterProjectNameKeyword')" />

  <!-- 获取当前语言 -->
  <div>{{ $i18next.language }}</div>
</template>

Script 中使用：

vue
<script setup lang="ts">
import { useTranslation } from 'i18next-vue'

// 使用 useTranslation hook 获取翻译函数
const { t, i18next } = useTranslation()

// 在逻辑中使用翻译
const rules = [
  { required: true, message: t('projectNameCannotBeEmpty') },
  { max: 32, message: t('cannotExceed32Chars') }
]

// 在函数中使用
function showMessage() {
  message.success(t('createSuccess'))
}

// 获取当前语言
console.log(i18next.language)
</script>

语言切换组件：

vue
<script setup lang="ts">
import { useTranslation } from 'i18next-vue'

const { i18next } = useTranslation()
</script>

<template>
  <Select
    :default-value="$i18next.language"
    @change="(lng: string) => i18next.changeLanguage(lng)"
  >
    <Select.Option value="zh-CN">
      简体中文
    </Select.Option>
    <Select.Option value="en-US">
      English
    </Select.Option>
  </Select>
</template>

其他导入方式：

vue
<script setup lang="ts">
// 1. 使用 useTranslation hook（推荐）
import { useTranslation } from 'i18next-vue'

// 2. 导入特定函数
import { changeLanguage } from '@/plugins/i18next'
// 3. 导入自定义翻译函数（用于特殊场景）
// import { translate } from '@/plugins/i18next'

const { t, i18next } = useTranslation()
</script>

操作指南

1. 添加新的翻译文本

  1. 在中文语言包中添加新条目

    bash
    # 编辑 locales/zh-CN.json
{
  "newKey": "新的中文文本",
  "withVariable": "包含变量的文本: {{value}}"
}

  2. 运行翻译命令生成英文版本

    bash
    pnpm run i18n

    该命令会调用 env-cmd lobe-i18n locale，使用 AI 自动翻译新增的文本

  3. 在代码中使用

    vue
    <!-- 模板中 -->
<div>
 {{ $t('newKey') }}
 </div>

<div>
 {{ $t('withVariable', { value: 'test' }) }}
 </div>

<!-- Script 中 -->
<script setup>
import { useTranslation } from 'i18next-vue'

const { t } = useTranslation()
console.log(t('newKey'))
</script>

2. 修改现有翻译

  1. 修改中文语言包 (locales/zh-CN.json)
  2. 运行翻译命令更新英文版本
    bash
    pnpm run i18n

3. 批量翻译

如果有大量新增文本需要翻译：

bash
# 设置环境变量指定翻译模型（可选）
export OPENAI_MODEL_NAME=azure/gpt-4o-mini

# 运行翻译
pnpm run i18n

4. 环境配置

确保设置正确的 AI 翻译服务配置：

bash
# 创建 .env 文件设置翻译相关环境变量
# 具体变量请参考 .env.example 中的相关注释

语言包结构规范

1. 命名规范

  • 使用小驼峰命名：projectName
  • 功能相关的分组：setting.appearance.theme.dark
  • 避免过长的嵌套，保持结构清晰

2. 文本规范

  • 中文语言包作为主要维护对象
  • 支持变量插值："tableTotal": "总共 {{count}} 个项目"
  • 保持简洁明了，避免冗余

3. 分类建议

json
{
  "common": {
    "confirm": "确认",
    "cancel": "取消"
  },
  "project": {
    "name": "项目名称",
    "create": "创建项目"
  },
  "error": {
    "networkError": "网络错误"
  }
}

开发流程

日常开发流程

  1. 在 locales/zh-CN.json 中添加新的翻译键值
  2. 运行 pnpm run i18n 生成英文翻译
  3. 在代码中使用 $t() 或 t() 函数
  4. 提交代码时包含翻译文件的更改

注意事项

  • 不要直接修改 en-US.json，它由工具自动生成
  • 翻译完成后检查生成的英文文本是否准确
  • 变量插值格式：{{variableName}}
  • 保持翻译键名的语义化和可维护性

故障排除

常见问题

  1. 翻译命令执行失败

    • 检查网络连接和 AI 服务配置
    • 确认 .i18nrc.cjs 配置正确

  2. 翻译结果不准确

    • 调整 temperature 参数（0-1，越小越稳定）
    • 检查源文本是否准确清晰

  3. 某些文本未被翻译

    • 确认新增的文本格式正确
    • 检查 JSON 语法是否有错误

  4. 开发环境中翻译不生效

    • 确认 i18next 初始化正确
    • 检查语言包是否正确导入
    • 重启开发服务器

调试方法

  1. 开启调试模式

    typescript
    i18next.init({
  debug: true, // 开启调试日志
  // ...
})

  2. 检查当前语言设置

    javascript
    console.log(i18next.language) // 当前语言
console.log(i18next.store.data) // 所有语言数据

相关命令

命令说明
pnpm run i18n执行国际化翻译，将中文翻译为英文
env-cmd lobe-i18n locale直接调用翻译工具

参考资源