Fibona I18n 工具

基于 AI 的多语言翻译工具，支持中文、英语、日语和韩语之间的互译。

1. 安装

1.1 全局安装（推荐）

# 使用 npm 安装
npm install -g fibona-tnpm

# 或使用 yarn
yarn global add fibona-tnpm

# 或使用 pnpm
pnpm add -g fibona-tnpm

# 安装后可以直接使用命令
ftn config --targetLanguages "ja"

1.2 本地安装

# 使用 npm 安装到项目中
npm install fibona-tnpm

# 在 package.json 中添加命令
{
  "scripts": {
    "ftn": "ftn"
  }
}

# 使用 npm run 执行命令时需要加上 -- 来传递参数
npm run ftn -- config --targetLanguages "ja"

注意：使用 npm run 执行命令时，必须在命令和参数之间添加 --，这样参数才能正确传递给实际命令。例如：

• ❌ npm run ftn config --targetLanguage ja（错误）
• ✅ npm run ftn -- config --targetLanguages "ja"（正确）

1.3 本地开发

1.3.1 开发模式

适用于本地开发和调试：

# 1. 安装依赖
pnpm install

# 2. 启动开发模式（使用 unbuild --stub 实现快速构建）
pnpm dev

# 3. 创建全局链接
pnpm link --global

# 现在可以全局使用命令了
ftn --help

开发模式下的修改会通过 unbuild --stub 快速生效，非常适合本地开发和调试。

1.3.2 生产构建

发布前需要进行生产构建：

# 构建生产版本
pnpm build

注意事项：

• 开发时使用 pnpm dev + pnpm link --global 的组合，支持实时修改
• 发布前使用 pnpm build 进行生产构建
• 所有构建过程都会自动处理文件权限，无需手动设置

2. 基本命令

2.1 登录认证

# 全局安装时：
# 登录
ftn login

# 登出
ftn logout

# 本地安装时：
# 登录
npm run ftn -- login

# 登出
npm run ftn -- logout

登录成功后，认证信息会保存在用户目录下，后续命令会自动使用保存的认证信息。

2.2 项目初始化

# 全局安装时：
# 初始化项目
ftn init

# 本地安装时：
# 初始化项目
npm run ftn -- init

# 初始化过程会要求配置：
# - 源语言 (如: zh)
# - 目标语言 (如: ja,ko)
# - 源文件目录 (默认: i18n/source)
# - 输出目录 (默认: i18n/fibonaI18n)
# - AI 提供商 (hunyuan/openai)

2.3 配置管理

# 查看当前配置
ftn config
# 或
npm run ftn -- config

# 查看配置帮助
ftn config --help
# 或
npm run ftn -- config --help

# 更新配置
ftn config [选项]
# 或
npm run ftn -- config [选项]

# 可用选项：
#   --sourceLanguage     源语言代码 (zh/en/ja/ko)
#   --targetLanguages    目标语言代码，多个用逗号分隔 (zh/en/ja/ko)
#   --sourceDir         源文件目录
#   --outputDir         输出文件目录
#   --aiProvider        AI 提供商 (hunyuan/openai)
#   --autoTranslate     是否自动翻译 (true/false)

# 示例：
# 全局安装时：
ftn config --sourceLanguage zh --targetLanguages "ja"
ftn config --sourceLanguage en --targetLanguages "zh"
ftn config --aiProvider hunyuan
ftn config --autoTranslate true

# 本地安装时：
npm run ftn -- config --sourceLanguage zh --targetLanguage ja
npm run ftn -- config --sourceLanguage en --targetLanguage zh
npm run ftn -- config --aiProvider hunyuan
npm run ftn -- config --autoTranslate true

注意事项：

1. 多个目标语言用逗号分隔，不要加空格
2. 本地安装时记得使用 -- 分隔符
3. 语言代码说明：
   • zh: 中文
   • en: 英语
   • ja: 日语
   • ko: 韩语

2.4 翻译功能

# 全局安装时：
# 翻译文件（默认按照配置的源语言和目标语言进行翻译）
ftn translate

# 指定源文件和目标语言
ftn translate --source-path i18n/source/zh.json --target-language ja

# 本地安装时：
# 翻译文件
npm run ftn -- translate

# 指定源文件和目标语言
npm run ftn -- translate --source-path i18n/source/zh.json --target-language ja

可用选项：

• --source-path: 源文件路径，默认使用配置中的 sourceDir
• --target-language: 目标语言代码，默认使用配置中的 targetLanguages
• --force: 强制重新翻译已翻译的内容
• --dry-run: 预览模式，不实际执行翻译

示例：

# 全局安装时：
# 强制重新翻译
ftn translate --force

# 预览翻译内容
ftn translate --dry-run

# 本地安装时：
# 强制重新翻译
npm run ftn -- translate --force

# 预览翻译内容
npm run ftn -- translate --dry-run

3. 项目结构

3.1 目录结构

your-project/
├── i18n/
│   ├── source/           # 源语言文件目录
│   │   ├── zh.json      # 中文源文件
│   │   ├── ja.json      # 日语翻译文件
│   │   └── ko.json
│   │   └── ...
│   └── fibonaI18n/      # 工具生成的文件
│       ├── untranslated.json    # 未翻译内容
│       └── ai_translations.json  # AI翻译结果

3.2 配置文件

// .fibona-i18nrc.json
{
  "sourceDir": "i18n/source",
  "outputDir": "i18n/fibonaI18n",
  "aiProvider": "hunyuan",
  "autoTranslate": false,
  "translation": {
    "sourceLanguage": "zh",
    "targetLanguages": ["ja"]
  }
}

4. 翻译流程

1. 准备源文件

   • 在 source 目录下创建源语言文件（如 zh.json）
   • 使用标准 JSON 格式

   {
     "hello": "你好",
     "welcome": "欢迎使用"
   }

2. 执行翻译

   ftn translate

3. 审核流程

   • 工具会显示未翻译的内容
   • AI 翻译完成后，可以选择：
     1. 接受翻译结果
     2. 拒绝翻译结果

4. 查看结果

   • 翻译结果保存在目标语言文件中
   • 可以在 fibonaI18n 目录查看详细信息

5. 最佳实践

1. 源文件管理

   • 保持源文件格式统一
   • 使用有意义的键名
   • 避免特殊字符

2. 翻译审核

   • 定期检查翻译质量
   • 对重要内容进行人工审核
   • 保存可靠的翻译结果

3. 版本控制

   • 将配置文件纳入版本控制
   • 可以将 fibonaI18n 目录添加到 .gitignore

6. 常见问题

1. 认证失败

   # 重新登录
   ftn logout
   ftn login

2. 配置问题

   # 检查配置
   ftn config
   
   # 重置配置
   rm .fibona-i18nrc.json
   ftn init

3. 翻译质量

   • 检查源文本是否规范
   • 考虑使用更正式的表述
   • 必要时调整 AI 提供商

7. 支持的语言

• 中文 (zh)
• 英语 (en)
• 日语 (ja)
• 韩语 (ko)

8. 更新日志

请参考项目仓库的 CHANGELOG.md 文件。

9. 获取帮助

# 查看命令帮助
ftn --help
ftn <command> --help

# 例如
ftn config --help

10. 许可证

MIT License