PHP 怎么PHP Crowdin

wen PHP项目 2026-08-01 1

**
《PHP国际化实战：从零掌握Crowdin本地化工作流,告别硬编码文案》

PHP 怎么PHP Crowdin

目录导读

为什么PHP项目需要Crowdin？—— 从硬编码到自动化翻译的痛与解
环境准备：PHP项目接入Crowdin前的三把钥匙（API令牌、文件格式、语言映射）
实战四步曲：如何用Crowdin CLI同步您的PHP语言包
进阶技巧：翻译记忆库、术语表与占位符保护（防止{name}被译者误改）
高频问答：常见报错、中文翻译质量差、多分支同步的解决方案
从“翻译文档”到“翻译产品”的思维跃迁

为什么PHP项目需要Crowdin？
很多PHP开发者早期习惯用 $lang['welcome_msg'] = 'Welcome'; 来管理语言包，但当项目发展到20个语言版本时，痛点骤然浮现：

产品经理用Excel催翻译，开发手动导入Array文件，来回修改极易发生键名错位；
外包翻译无法直接预览上下文，导致“Submit”被直译为“提交”而不是“提交订单按钮”；
代码里的占位符 %s 经常被译者当成拼写错误删除。

Crowdin 的核心价值在于“割裂翻译与发版”，它基于云端，允许您上传 PHP 语言数组文件（如 en.php、zh-CN.php），翻译完成后自动生成目标语言文件，更关键的是，它支持“在线上下文截图”——译员在翻译 login_btn 时能直接看到登录页的UI截图,从而理解该词是按钮还是导航标题。

环境准备：三把钥匙打开本地化大门

第一把钥匙：Crowdin 项目创建与 API 密钥。
登录 Crowdin 后台，创建项目后，在“Settings” -> “API” 中生成 api_key，该密钥有读写权限，务必存放于服务器环境变量中，切勿提交至 Git 仓库。

第二把钥匙：文件格式识别。
Crowdin 原生支持 PHP 数组格式，但您需要明确指定标识符前缀，您的源语言文件为 lang/en.php如下：

return [
    'homepage.title' => 'Welcome to Our Site',
    'footer.copyright' => '© {year} Company'
];

在 Crowdin 的“文件管理”中，选择“PHP Array”解析器，并设置“数组键表示方式”为 key -> full path（即 homepage.title 作为完整键名，而非嵌套数组）,这能避免多层数组解析时的键冲突。

第三把钥匙：语言映射规则。
建议将 Crowdin 中的语言代码与您的系统代码统一，后台设置“Chinese Simplified”映射为 zh-CN，但在步骤3的配置文件里，您需要将 zh-CN 转换为目标路径 lang/zh-CN.php。

实战四步曲：用 Crowdin CLI 实现命令行同步

安装 Crowdin CLI
推荐使用官方 Docker 镜像，避免本机 Node 版本冲突：

docker pull crowdin/cli

编写 crowdin.yml 配置文件
以下为精简配置示例：

project_id: "123456"
api_token_env: CROWDIN_API_TOKEN
base_path: "."
preserve_hierarchy: true
files:
  - source: "/lang/en.php"
    translation: "/lang/%two_letters_code%.php"
    # 如果目标语言是繁体中文，需自定义映射
    languages_mapping:
      two_letters_code:
        zh-CN: "zh-CN"
        zh-TW: "zh-TW"

推送源文件与拉取翻译

# 推送英文源文件，等待翻译完成
docker run -v $(pwd):/app crowdin/cli push sources
# 下载所有已完成的翻译（或指定语言）
docker run -v $(pwd):/app crowdin/cli pull -l zh-CN

集成到 CI/CD 流水线
在 GitLab CI 中，您可以在构建镜像前执行 pull 命令，确保最新翻译随代码上线，注意：避免在 push sources 时触发 pull,否则会有不一致风险。

进阶技巧：保护代码占位符与提升翻译一致性

问题场景：英文串 Order #%d for %s has shipped 翻译为中文时，%d 和 %s 可能被调换位置。

Crowdin 解法：在项目设置中打开 “占位符验证”，并添加正则模式 %[a-z]，此时译文若缺少或多余占位符，系统会阻止保存。

术语表：对于“Product SKU”、“Premium Member”等专有名词，在“术语管理”中定义源语言和目标语言，这样，译者选择“Premium Member”时，下方会强调建议译法“高级会员”，避免“尊贵会员”等不一致翻译。

翻译记忆库：当更新 en.php 时，比如将 welcome_msg 从 “Hello” 改为 “Hello there”，仅改动部分的翻译成本会降低 30%，因为 Crowdin 会复用旧翻译的模糊匹配片段。

高频问答

Q1：执行 pull 后，生成的文件中文乱码？
原因：Crowdin 默认输出 UTF-8 编码，但您的 PHP 文件头部没有声明 header('Content-Type: text/html; charset=utf-8'); 或未在项目级添加 mb_internal_encoding，请在 PHP 文件入口设置，并确保源文件 en.php 同样为 UTF-8 无 BOM 格式。

Q2：如何让翻译在每晚定时同步，而非每次手动？
方案A：使用 GitHub Actions 的 Cron 调度器，每日凌晨运行 docker run crowdin/cli pull 并自动提交 PR，方案B：在 Crowdin 后台的“Integrations”中绑定 GitHub，开启“Synchronize on push”自动创建翻译 PR。

Q3：Crowdin 支持 Yii/Laravel 的函数解析吗？
Crowdin 本身只认文件格式，Laravel 语言文件是 PHP 数组，原理相同，但对于 Yii 的 message 格式（含有文件头注释），可以在配置文件中设置 file_extension: .php 并忽略注释,即可正常解析。

Q4：翻译人员误将键名（如 homepage.title）改动了怎么办？
在 Crowdin 项目设置中的“TM”设置里，勾选 “字符串标识符不允许修改”，若已发生误改，您需要从 Git 历史恢复 zh-CN.php，重新推送该文件并执行 pull 覆盖。

Q5：免费版有文件数量限制吗？
Crowdin 免费计划提供 1 个公共项目、最多 2 个私密项目，文件数量不限制，但总字符串容量（免费为 10,000 字符）有限，超过后需要截断历史版本或升级，若预算有限，可考虑将不常更新的语言包（如 errors.php）合并进一个主文件。

在 PHP 项目中引入 Crowdin，不仅仅是把翻译外包，更是建立一套内容运营体系，当您的 en.php 更新时，不再需要给翻译公司发Zip包；当新版本上线前，产品经理能在 Crowdin 看板上一目了然地了解各语言翻译进度；当热更新中出现 {user_name} 变量被破坏时，占位符校验能提前预警。

最后建议：把 source 文件从 en.php 改为 source.php，因为英语本身也是一种翻译语言，这样当您未来想从法语源切换时，只需调整 crowdin.yml 中的 source 路径即可，而不会污染历史翻译记忆，让您的语言包像代码一样，拥有版本管理、单元测试（占位符检查）和持续交付能力——这才是现代化 PHP 国际化的终极形态。