企业官网建设流程全解析

1. 为什么需要自动化翻译流水线

在开发多语言项目时，手动管理翻译文件就像用勺子给游泳池排水——理论上可行，但效率低到让人怀疑人生。我经历过一个项目，每次更新文案都要手动复制粘贴几十个JSON文件，最后因为漏了一个逗号导致整个前端崩溃。这种痛苦让我意识到：自动化翻译流程不是可选项，而是生存必需品。

Crowdin作为专业的本地化平台，其CLI工具能完美解决这个问题。通过将Crowdin CLI与npm脚本结合，你可以实现：

• 源文件自动上传：代码中的新增文案自动同步到翻译平台
• 翻译进度监控：在CI流程中实时检查各语言完成度
• 译文自动下载：翻译完成的文件自动回归代码库
• 版本控制集成：所有变更与git提交记录关联

2. 环境准备与基础配置

2.1 安装Crowdin CLI

首先全局安装CLI工具（建议使用yarn避免权限问题）：

yarn global add @crowdin/cli # 验证安装 crowdin --version

遇到过安装失败的情况？可能是Node版本问题。我实测v16.x最稳定，如果遇到EBUSY错误，试试加上--ignore-engines参数。

2.2 项目初始化

在项目根目录执行初始化：

crowdin init

这会交互式生成crowdin.yml配置文件。关键参数说明：

踩坑提醒：如果项目使用monorepo结构，需要特别处理路径映射。比如我的一个项目结构如下：

packages/ web/ locales/ # 前端翻译文件 mobile/ res/ # 移动端资源目录

这时要在crowdin.yml中使用preserve_hierarchy: true保持目录结构。

3. 配置文件深度定制

3.1 多文件类型配置

现代项目通常混合多种文件格式，这是我的一个真实配置示例：

files: - source: '/src/locales/en/*.json' translation: '/src/locales/%locale%/%original_file_name%' type: json - source: '/docs/**/*.md' translation: '/docs/%locale%/%original_path%/%original_file_name%' type: markdown skip_untranslated_strings: true

实用技巧：使用%original_path%变量可以完美保持子目录结构，这对文档类项目特别有用。

3.2 语言映射配置

当你的语言代码与Crowdin标准不同时（比如用zh-Hans而非zh-CN）：

languages_mapping: locale: 'zh-CN': 'zh-Hans' 'zh-TW': 'zh-Hant' three_letters_code: 'zh-Hans': 'zho'

4. npm脚本集成实战

4.1 基础命令封装

在package.json中添加这些脚本：

{ "scripts": { "i18n:upload": "crowdin upload sources", "i18n:download": "crowdin download", "i18n:sync": "run-s i18n:upload i18n:download", "i18n:status": "crowdin status" } }

性能优化：大项目可以添加--dryrun参数先预览变更：

crowdin download --dryrun

4.2 CI/CD集成示例

这是我在GitHub Actions中的配置片段：

- name: Sync translations env: CROWDIN_API_KEY: ${{ secrets.CROWDIN_API_KEY }} run: | yarn i18n:sync git config --global user.name "i18n Bot" git add ./locales git commit -m "i18n: update translations [skip ci]" git push

避坑指南：记得在CI中设置fail_on_warnings: false，否则翻译中的警告会导致构建失败。

5. 高级技巧与故障排查

5.1 增量同步优化

通过export_pattern实现按需导出：

files: - source: '/src/messages/en.json' translation: '/src/messages/%locale%.json' update_option: 'update_without_changes' export_pattern: '/src/messages/%locale%_delta.json'

5.2 常见错误解决

• ETIMEDOUT错误：在crowdin.yml中添加：

  api: request_timeout: 30000

• 校验失败：检查文件编码必须是UTF-8，BOM头会导致解析失败
• 权限问题：尝试添加--no-progress参数减少网络负载

6. 监控与优化

建议在CI流程中加入这些检查：

# 检查翻译完成度 crowdin status --language=ja --fail-if-incomplete=90 # 验证文件结构 crowdin list project --tree

我在团队中建立了这样的规则：当主要语言翻译完成度低于95%时自动阻塞发布流程，这显著减少了上线后的语言问题。