Crowdin 适配器 - hyperlocalise

两个 Crowdin 工作流

Hyperlocalise 现在支持两种不同的 Crowdin 集成：

原生同步模式，带有i18n.yml加上sync push / sync pull
兼容 Crowdin 的文件模式，带有 crowdin.yml 和 hyperlocalise crowdin ...

当你想要使用 Hyperlocalise 管理的条目同步时，请使用原生同步模式。当你希望更贴近 Crowdin CLI 文件工作流的即插即用替代方案时，请使用文件模式。

原生同步模式

必需配置

{
  "storage": {
    "adapter": "crowdin",
    "config": {
      "projectID": "123456",
      "apiTokenEnv": "CROWDIN_API_TOKEN"
    }
  }
}

Crowdin 企业

当你的工作区使用 Crowdin Enterprise 而不是默认的 Crowdin Cloud API 时，请设置 apiBaseURL。

{
  "storage": {
    "adapter": "crowdin",
    "config": {
      "projectID": "123456",
      "apiTokenEnv": "CROWDIN_API_TOKEN",
      "apiBaseURL": "https://example.api.crowdin.com"
    }
  }
}

可选配置字段

apiBaseURL：覆盖 Crowdin API 基础 URL。用于 Crowdin Enterprise。
sourceLanguage
targetLanguages
timeoutSeconds

兼容 Crowdin 的文件模式

使用 crowdin.yml 或 crowdin.yaml。示例：

project_id_env: CROWDIN_PROJECT_ID
api_token_env: CROWDIN_PERSONAL_TOKEN
preserve_hierarchy: true

files:
  - source: /src/messages.json
    translation: /locales/%locale%/%original_file_name%
    export_only_approved: true

v1 中支持的crowdin.yml字段：

project_id
project_id_env
api_token
api_token_env
base_url
base_url_env
base_path
base_path_env
branch
preserve_hierarchy
files[].source
files[].translation
files[].languages_mapping
files[].excluded_target_languages
files[].skip_untranslated_strings
files[].skip_untranslated_files
files[].export_only_approved

使用兼容的 CLI 接口：

hyperlocalise crowdin init
hyperlocalise crowdin config validate
hyperlocalise crowdin upload sources
hyperlocalise crowdin upload translations --language fr
hyperlocalise crowdin download --language fr --export-only-approved --skip-untranslated-strings
hyperlocalise crowdin download --language fr --merge-approved
hyperlocalise crowdin download --language fr --include-sources

--merge-approved 将已批准的 JSON 对象键合并到现有的本地翻译文件中，并保留 Crowdin 已批准导出中省略的本地键。当 Crowdin 在该导出中包含源语言回退值时，Hyperlocalise 会跳过那些仍与源 JSON 匹配的值，因此先前翻译过的本地字符串会被保留。 --include-sources 也会在写入翻译之前，将匹配的 Crowdin 源文件下载到已配置的 files[].source 路径中。如果缺少精确的源路径，则可以在本地创建；通配的源路径仅限于本地 glob 展开匹配到的文件。在 branch: 中使用根目录，或传入 crowdin.yml 和 --branch <name>，以从 Crowdin 分支上传和下载文件。该标志会覆盖该命令的配置值。在不支持的 Crowdin 字段或命令上，验证会失败并保持关闭。

常见问题

找不到令牌：导出 CROWDIN_API_TOKEN
企业 API 请求失败：请验证 storage.config.apiBaseURL 是否指向你的企业 API 主机，并使用 https
项目查找失败：请检查项目 ID 和账户权限
部分更新：查看带有 --output json 的冲突报告
文件模式验证错误：移除不受支持的crowdin.yml字段，或切换为原生i18n.yml同步模式

​两个 Crowdin 工作流

​原生同步模式

​必需配置

​Crowdin 企业

​可选配置字段

​兼容 Crowdin 的文件模式

​常见问题