Crowdin CLI 3.x 实战5分钟自动化同步Vue项目多语言JSON与Markdown文件1. 为什么选择Crowdin CLI进行前端国际化在全球化数字产品的今天多语言支持已成为前端开发的标配需求。传统的国际化流程往往面临以下痛点人工管理翻译文件效率低下随着语言版本增加手动维护en.json/zh-CN.json等文件变得异常繁琐协作流程断裂开发人员需要将文件发送给翻译团队再手动合并回代码库版本控制混乱翻译进度与代码版本不同步导致发布时出现遗漏Crowdin CLI作为专业的本地化命令行工具提供了完整的解决方案# 主要功能概览 crowdin upload sources # 上传源文件 crowdin download # 下载翻译结果 crowdin list project # 查看项目文件状态关键优势对比传统方式Crowdin CLI方案手动复制粘贴翻译内容自动同步翻译文件邮件/Slack沟通进度平台实时查看翻译进度单一文件格式支持同时处理JSON/Markdown/HTML等无版本控制与Git分支深度集成2. 环境配置与项目初始化2.1 安装CLI工具推荐使用npm全局安装需要Node.js 14环境npm install -g crowdin/cli3 # 或使用yarn yarn global add crowdin/cli3验证安装成功crowdin --version # 应输出类似3.7.02.2 项目配置文件初始化在Vue项目根目录执行crowdin init根据提示完成配置浏览器完成OAuth认证输入项目ID在Crowdin项目设置中查找设置基础路径通常为当前目录.生成的核心配置文件crowdin.yml示例project_id: 123456 api_token: your_api_token base_path: . preserve_hierarchy: true files: [ { source: src/locales/en/*.json, translation: src/locales/%locale%/%original_file_name% }, { source: docs/**/*.md, translation: docs/%locale%/**/%original_file_name% } ]提示将crowdin.yml加入.gitignore避免泄露API密钥3. Vue项目结构适配实战3.1 典型Vue i18n项目结构假设项目采用vue-i18n方案推荐目录结构src/ locales/ en/ # 英文源文件 common.json dashboard.json zh-CN/ # 中文翻译 common.json dashboard.json docs/ en/ # 英文文档 getting-started.md zh-CN/ # 中文文档 getting-started.md3.2 配置优化技巧针对Vue项目的特殊配置# crowdin.yml 增强配置 files: [ { source: src/locales/en/*.json, translation: src/locales/%locale%/%original_file_name%, update_option: update_without_changes # 保留未修改字段 }, { source: docs/**/*.md, translation: docs/%locale%/**/%original_file_name%, skip_untranslated_strings: true # 跳过未翻译文档 } ] # 语言映射解决zh-CN与zh-Hans的兼容问题 language_mapping: { zh-CN: zh-Hans, zh-TW: zh-Hant }4. 自动化工作流实现4.1 基础npm脚本配置在package.json中添加{ scripts: { i18n:upload: crowdin upload sources, i18n:download: crowdin download, i18n:sync: run-s i18n:upload i18n:download, i18n:preview: crowdin download --dry-run } }常用命令说明npm run i18n:upload只上传新增/修改的源文件npm run i18n:download下载所有可用翻译npm run i18n:preview预览将要下载的文件不实际写入4.2 高级Git集成方案实现按分支管理翻译#!/bin/bash # pre-commit.sh # 获取当前分支 BRANCH$(git rev-parse --abbrev-ref HEAD) # 只在上传源文件时处理特定分支 if [[ $BRANCH main ]]; then crowdin upload sources -b $BRANCH git add src/locales/en/* git commit -m i18n: update source strings fi4.3 CI/CD集成示例GitHub Actions# .github/workflows/i18n-sync.yml name: i18n Sync on: push: branches: [ main ] schedule: - cron: 0 12 * * * # 每天UTC时间12点同步 jobs: sync: runs-on: ubuntu-latest steps: - uses: actions/checkoutv3 - name: Setup Node uses: actions/setup-nodev3 with: node-version: 16 - name: Install Crowdin CLI run: npm install -g crowdin/cli3 - name: Download translations env: CROWDIN_API_KEY: ${{ secrets.CROWDIN_API_KEY }} run: | crowdin download -b main git config --global user.name i18n Bot git config --global user.email i18n-botexample.com git add src/locales/* git commit -m i18n: update translations [skip ci] || echo No changes git push5. 疑难问题解决方案5.1 常见错误处理问题1上传时出现File not found错误解决方案# 检查文件路径是否匹配 crowdin list project --tree # 更新配置中的source路径问题2Markdown中的代码块被破坏配置调整# crowdin.yml files: [ { source: docs/**/*.md, translation: docs/%locale%/**/%original_file_name%, type: md, escape_special_characters: false # 保留原始格式 } ]5.2 性能优化技巧对于大型项目# 使用多线程上传默认5线程 crowdin upload sources -p 10 # 仅下载特定语言 crowdin download -l zh-CN,ja # 排除测试文件 files: [ { source: src/locales/en/*.json, translation: src/locales/%locale%/%original_file_name%, excluded_target_languages: [test] } ]5.3 翻译质量保障推荐工作流启用Crowdin的QA检查配置术语表(Glossary)使用翻译记忆库(TM)# 下载翻译前进行预翻译 crowdin pre-translate -l zh-CN --method tm