用途
本技能提供一套生产就绪的架构,用于将 Lokalise 翻译管理系统(TMS)集成到 Web 应用中。它覆盖从源代码经 CI/CD 和 Lokalise 到已部署翻译的端到端翻译流程,适合在设计新的 Lokalise 集成、审查项目结构或规划翻译交付策略时使用。
前置条件
- Node.js 18+ 与 TypeScript
- 已安装 @lokalise/node-api SDK(npm install @lokalise/node-api)
- 已选定 i18n 框架(i18next、react-intl、vue-i18n 或同类)
- 已创建 Lokalise 项目并配置至少一种源语言
- 对 CI/CD 流水线(GitHub Actions、GitLab CI 或同类)有基本了解
主要能力
1. 架构流程
翻译生命周期包含两条交付路径:
- 构建时(build-time):翻译在 CI 构建期间下载并打包进应用,变更需要重新部署。
- OTA(over-the-air):翻译在运行时从 Lokalise CDN 获取,变更无需重新部署即可生效,但增加网络依赖。
2. i18n 项目结构
将翻译关注点与业务逻辑分离,推荐目录包括:
- src/i18n/:index.ts(初始化与配置)、client.ts(Lokalise API 客户端封装)、loader.ts(翻译加载器)、fallback.ts(回退逻辑)、types.ts(翻译键类型)、middleware.ts(语言检测中间件)
- src/locales/:各语言 JSON 文件(en.json 为源语言并提交到 git,其他语言从 Lokalise 下载)
- src/locales-fallback/:始终提交的静态回退副本
- scripts/:lokalise-pull.sh、lokalise-push.sh、validate-translations.ts、generate-types.ts
- .github/workflows/:lokalise-upload.yml、lokalise-download.yml
- lokalise.config.ts:Lokalise 项目配置
3. 核心配置
提供 i18next 初始化示例,定义 SUPPORTED_LOCALES、DEFAULT_LOCALE,配置 fallbackLng、supportedLngs、load: 'languageOnly'、returnEmptyString: false 以及语言检测顺序(cookie、navigator、htmlTag)。
4. Lokalise API 客户端封装
提供 LokaliseClient 类,封装 @lokalise/node-api,包含:
- downloadTranslations():下载全部翻译文件并返回 zip 包 URL,支持 format、branch 选项
- 内置简单限流器(默认每秒最多 6 次请求)
- 其他方法(listKeys()、getStatistics()、uploadFile())遵循相同模式,每次 API 调用前先调用 rateLimit()
5. 文件组织约定
- 扁平键(推荐):如 homepage.hero.title、settings.profile.name_label
- 嵌套键:适合模块边界清晰的大型项目
- 键命名:点号表示法 module.section.element,键段用 snake_case,按功能区域加前缀,使用一致后缀(_title、_label、_button、_error、_placeholder),键名保持在 100 字符以内(Lokalise 硬限制为每个键名 1024 字符)
- 文件命名:每个语言一个文件;大型应用可按命名空间拆分(common.json、auth.json、dashboard.json)并放入子目录
6. 多应用翻译共享
当多个应用(Web、移动端、营销站点)共享翻译时,推荐在单一 Lokalise 项目中使用基于标签的过滤:
- 使用 shared、web-only、mobile-only、marketing-only 等标签
- 通过 lokalise2 file download 命令配合 --filter-tags 参数按标签下载
- 注意:Lokalise 不原生支持跨项目共享键,因此单项目内标签过滤是推荐方案
7. OTA 与构建时加载的取舍
对比维度包括:延迟、更新速度、离线支持、包体积、可靠性、最佳适用场景。
- 构建时:零延迟、需部署更新、完全离线支持、包体积随语言增加、无外部依赖,适合服务端渲染应用和带 CI/CD 的 SPA
- OTA:首次加载有网络请求、更新即时、需初始获取加本地缓存、包体积最小、依赖 Lokalise CDN,适合移动应用和快速文案变更
- 混合方案(推荐用于生产):先立即加载打包翻译,再在后台尝试 OTA 更新,OTA 冲突时以 OTA 为准
8. TypeScript 类型安全
提供 generate-types.ts 脚本,从源语言 JSON 生成 TranslationKey 联合类型,实现编译期键校验。示例中 t('homepage.hero.title') 合法,t('homepage.hero.titl') 会触发 TypeScript 错误。
使用方式
按技能中的步骤依次实施:绘制架构图、搭建项目结构、编写核心配置、封装 API 客户端、遵循文件组织约定、配置多应用共享、选择加载策略、生成 TypeScript 类型。
适用场景
- 设计新的 Lokalise 集成
- 审查现有 i18n 项目结构
- 规划翻译交付策略(构建时、OTA 或混合)
- 多应用共享翻译的场景
限制与注意事项
- Lokalise 不原生支持跨项目共享键,需在单项目内用标签过滤
- OTA 依赖 Lokalise CDN,存在网络依赖
- 构建时方案每次翻译变更都需要重新部署
- 标签名称区分大小写,拼写错误会导致下载为空
- 类型生成器需过滤数组值,Lokalise 不应产生数组
- 具体收费、价格、平台支持范围等资料未提供
输出结果
应用本技能后,项目将具备:清晰的翻译流程架构、分离的 i18n 项目结构、带限流的 Lokalise API 客户端封装、遵循命名约定的文件组织、基于标签的多应用翻译共享、选定的翻译加载策略,以及用于编译期键校验的 TypeScript 类型生成。
错误处理
技能列出常见问题及解决方案,包括:i18n 模块循环导入、运行时缺少语言文件、部署后翻译陈旧、类型生成失败、OTA 翻译加载闪烁、包体积过大、标签下载返回空等。
后续步骤
- 设置 lokalise-ci-integration 在 CI 中自动化上传/下载循环
- 配置 lokalise-multi-env-setup 实现按环境隔离项目
- 上线前运行 lokalise-prod-checklist 验证覆盖率和安全性
- 将 TypeScript 类型生成器实现为 pre-commit 钩子以保持类型同步