Flutter i18n Tool

🚀 Flutter GetX国际化智能翻译工具 - 支持代码扫描和AI自动翻译

特性

• 🔍 智能扫描: 自动扫描Flutter项目中的tr()翻译调用
• 🤖 AI翻译: 支持OpenAI API进行多语言自动翻译
• 📦 批量处理: 支持大量翻译文本的批量处理
• 🔄 增量更新: 只翻译新增或变更的内容，节省API调用
• 📊 详细报告: 提供扫描和翻译的详细报告
• 🛠️ 易于配置: 支持交互式配置和自定义设置
• 💾 备份机制: 自动备份翻译文件，防止数据丢失
• 🌍 多语言支持: 内置多种语言配置

安装

全局安装

npm install -g flutter-i18n-tool

本地安装

npm install flutter-i18n-tool --save-dev

快速开始

1. 初始化项目

# 在Flutter项目根目录运行
flutter-i18n-tool init

# 或指定项目路径
flutter-i18n-tool init /path/to/your/flutter/project

2. 配置API密钥

flutter-i18n-tool config

3. 扫描并翻译

# 自动扫描并翻译所有语言
flutter-i18n-tool auto

# 或分步执行
flutter-i18n-tool scan        # 扫描翻译字段
flutter-i18n-tool translate   # 翻译所有语言

使用说明

在Flutter代码中使用翻译

确保在你的Flutter项目中使用以下格式的翻译调用：

// 基本用法
Text(tr('common.welcome', '欢迎'))

// 带参数的翻译
Text(tr('user.greeting', '你好 @name', params: {'name': userName}))

// 按钮文本
ElevatedButton(
  onPressed: () {},
  child: Text(tr('button.save', '保存')),
)

命令行选项

# 初始化
flutter-i18n-tool init [project-path]  # 初始化翻译工具
  -f, --force                           # 强制重新初始化

# 配置
flutter-i18n-tool config               # 交互式配置API密钥和语言

# 扫描
flutter-i18n-tool scan                 # 扫描项目翻译字段
  -d, --dirs <dirs>                     # 指定扫描目录，用逗号分隔

# 翻译
flutter-i18n-tool translate [language] # 翻译指定语言或所有语言
  -f, --force                           # 强制重新翻译所有字段

# 自动化
flutter-i18n-tool auto                 # 扫描 + 翻译
  -l, --languages <languages>          # 指定要翻译的语言

# 状态查看
flutter-i18n-tool status               # 查看翻译状态和配置信息
flutter-i18n-tool test                 # 测试API连接

# 工具
flutter-i18n-tool export [language]    # 导出翻译文件到项目
flutter-i18n-tool clean                # 清理生成文件
  --history                             # 只清理历史记录
  --all                                 # 清理所有生成文件

配置说明

环境变量

export OPENAI_API_KEY="your_api_key_here"
export OPENAI_BASE_URL="https://api.chatanywhere.tech/v1"  # 可选

支持的语言

• 🇹🇼 繁体中文 (zh_Hant)
• 🇺🇸 English (en)
• 🇯🇵 日本語 (ja)
• 🇰🇷 한국어 (ko)
• 🇻🇳 Tiếng Việt (vi)
• 🇹🇭 ไทย (th)
• 🇲🇾 Bahasa Malaysia (ms)

目录结构

初始化后会在项目同级目录创建输出文件夹：

your_project_translations_outputs/
├── config.json # 工具配置
├── history/ # 翻译历史记录
├── backups/ # 文件备份
├── reports/ # 扫描和翻译报告
└── temp/ # 临时文件

API支持

OpenAI兼容API

• OpenAI官方API
• ChatAnywhere API
• DeepSeek API
• 其他兼容OpenAI格式的API服务

模型配置

工具支持多个模型，会根据配额情况自动切换：

• gpt-3.5-turbo (低成本)
• gpt-4o-mini (低成本)
• deepseek-chat (低成本)
• gpt-4o (高成本，高质量)

最佳实践

1. 翻译键命名规范

// 推荐的命名方式
tr('common.button.save', '保存')           // 通用按钮
tr('page.home.title', '首页')              // 页面标题
tr('dialog.confirm.message', '确认操作？')  // 对话框消息
tr('error.network.timeout', '网络超时')     // 错误消息

2. 参数使用

// 正确使用参数
tr('user.welcome', '欢迎 @name 回来！', params: {'name': userName})

// 避免在参数中包含UI组件
tr('message.count', '共有 @count 条消息', params: {'count': messageCount.toString()})

3. 文件组织

ib/
├── app/
│ └── translations/
│ └── translation_utils.dart # 翻译工具
└── generated/
└── locales.g.dart # GetX生成的文件
assets/
└── locales/
├── zh_CN.json # 简体中文(基础语言)
├── zh_Hant.json # 繁体中文
├── en.json # 英语
└── ... # 其他语言

故障排除

常见问题

1. API连接失败

   flutter-i18n-tool test  # 测试API连接

2. 扫描不到翻译

   • 检查tr()方法格式是否正确
   • 确认文件在扫描目录内

3. 翻译质量问题

   • 调整温度参数（0.1-0.5）
   • 使用更高级的模型
   • 优化语言指令

4. GetX集成问题

   # 手动生成GetX文件
   get generate locales assets/locales

调试模式

设置环境变量启用详细日志：

export DEBUG=flutter-i18n-tool
flutter-i18n-tool auto

贡献

欢迎提交Issue和Pull Request！

许可证

MIT License

更新日志

v1.0.0

• 🎉 首次发布
• ✨ 支持AI自动翻译
• 🔍 智能代码扫描
• 📊 详细报告和状态显示
• 🛡️ 备份和历史记录