OpenProject 配置目录国际化规范i18n-tasks 工作流与 Crowdin 翻译管理实战【免费下载链接】openprojectOpenProject is the leading open source project management software for product, project and portfolio management. A powerful Jira alternative with agile planning, issue tracking, roadmaps, Gantt charts, time tracking, collaboration features, and more. Available on premises or in the cloud. ⭐ Star us on GitHub项目地址: https://gitcode.com/GitHub_Trending/op/openproject导读OpenProject 作为覆盖项目管理、敏捷看板与组合管理的开源软件其界面文本支持数十种语言而这背后是一套严格的“配置目录国际化i18n规范”。本文以仓库config/目录下的 AGENTS.md 约定为骨架系统讲解 OpenProject 的翻译键约束、en.yml源文件编辑方式、Crowdin 社区翻译协作流程以及i18n-tasks四个核心 CLI 命令的用法与底层原理并结合仓库源码说明前端 JS 翻译、复数化兜底等关键实现帮助开发者在参与 OpenProject 开发或自建多语言功能时快速上手。一、总体约定UI 字符串必须走翻译键config/AGENTS.md首先确立了一条铁律UI strings must use translation keys (never hard-coded)即界面字符串一律使用翻译键translation key严禁硬编码。这条约束在仓库中随处可见视图层通过t(...)/I18n.t(...)取键例如 app/components/admin/backups/reset_token_dialog_component.html.erb 中的按钮文案组件层则在 Ruby 中调用I18n.t。如此设计的目标是让“文本”与“逻辑”彻底解耦任何新增的 UI 文案都必须在英文源文件中登记一个键再由各语言文件提供对应翻译从而保证语言切换、复数规则、无障碍标签等能力的一致性。在组件开发层面OpenProject 对 ViewComponent 的惰性查找lazy lookup做了专门适配。app/components/translations_override.rb 注释解释了原因由于项目未使用 ViewComponent 自带的 sidecar 翻译文件VC 4.0 的#translate会转发到I18n.translate而项目依赖 ActionView 的覆盖实现来支持组件内的惰性键解析因此该模块显式include ActionView::Helpers::TranslationHelper。这意味着组件内的t(.some_key)相对键能够按“组件路径 方法名”正确解析参见 config/i18n-tasks.yml 中关于relative_roots与relative_exclude_method_name_paths的配置。二、英文源文件可以直接修改的en.yml文档规定源翻译存放在**/config/locales/en.yml中可以直接修改。这里的**通配符覆盖两层含义核心仓库config/locales/en.yml 是主英文翻译文件包含约 6000 余条键覆盖 accessibility、activerecord、work_package、project 等全部命名空间各功能模块OpenProject 以模块化方式组织代码29 个模块各自维护独立的config/locales/en.yml例如 modules/storages/config/locales/en.yml文件存储模块、modules/meeting/config/locales/en.yml 等。这也是 config/i18n-tasks.yml 中data.read读取来源的一部分。因此新增或修改英文文案时先定位该功能所属的模块目录再编辑对应en.yml根目录的config/locales/en.yml则承载核心应用文案。三、其他语言统一交给 Crowdin 管理与英文源文件不同其他语言的翻译统一由 Crowdin 管理开发者不应手工编辑config/locales/crowdin/下的 165 个语言文件涵盖 af、ar、az、de、fr、ja、zh 等。仓库 crowdin.yml 定义了与 Crowdin 平台的同步配置这一工作流带来的收益是翻译由社区译者分布式完成且版本回退、词条一致性检查都在平台侧完成。仓库中与 Crowdin 配套的脚本位于 script/i18n/generate_seeders_i18n_source_file把种子数据seeds中的默认内容如颜色名、默认状态名抽成可翻译的源文件文件头明确标注“This file has been generated … Please do not edit directly”见 config/locales/crowdin/de.seeders.ymlrewrite_crowdin_yml_files/fix_crowdin_pt_language_root_key处理 Crowdin 下载产物中的键根节点等格式问题generate_languages_translations基于 CLDR 数据代码中CLDR_VERSION 44生成本地化语言元数据test_seed_all_locales批量校验所有语言环境下种子数据的可加载性。此外config/locales/generated/存放生成产物en.yml、de.yml等按语言聚合的文件config/locales/js-en.yml 则是前端 JS 用的英文翻译源。整体目录分工可归纳为目录/文件角色编辑方式**/config/locales/en.yml英文源翻译含各模块开发者直接修改config/locales/crowdin/*.yml各语言社区翻译仅通过 Crowdin 平台config/locales/generated/*.yml生成/聚合产物脚本生成勿手改config/locales/js-*.yml前端 JS 翻译源按需更新英文源四、i18n-tasks 四件套检查、清理与归一化文档给出了开发者在提交翻译改动前必须运行的四个命令全部基于i18n-tasks这个 Ruby gem依赖声明见 Gemfile版本约束为~ 1.1.0require: false按需加载bundle exec i18n-tasks missing # Show missing translation keys bundle exec i18n-tasks unused # Show unused translation keys bundle exec i18n-tasks normalize # Fix/normalize translation files bundle exec i18n-tasks check-consistent-interpolations # Check interpolation consistency1.missing找出缺失的翻译键扫描代码中所有翻译调用对照各语言文件找出缺失的键。工具的搜索范围与规则在 config/i18n-tasks.yml 中定义search.paths默认搜索app/当前配置额外加入了modules/storages/app/模块内代码同样纳入检查exclude排除app/assets/images、app/assets/fonts、app/assets/videos、app/assets/builds等非代码资源目录strict模式默认 true下t(categories.#{category}.title)这类动态拼接会被识别为“猜测用法”从而避免误报。2.unused找出未使用的翻译键用于发现已被代码移除、但仍残留在语言文件中的键。为避免误报config/i18n-tasks.yml 配置了ignore_unused白名单例如ignore_unused: - activerecord.{models,attributes,errors}.* - permission_* - {devise,kaminari,will_paginate}.* - *.permission_header_explanation - storages.upsell.* - services.* - storages.health.checks.*这些键要么由 Rails 框架按约定动态查找如activerecord.attributes.*对应User.human_attribute_name(:email)要么由权限/服务等反射式机制使用静态扫描无法定位因此需要显式豁免。3.normalize归一化翻译文件对 YAML 文件做排序、键结构调整保证多语言文件结构一致避免合入 Crowdin 后产生大量无意义 diff。归一化遵循 config/i18n-tasks.yml 的data.write路由规则例如 storages 模块的键会被强制写入modules/storages/config/locales/%{locale}.yml其余键走config/locales/%{locale}.yml的 catch-all 规则YAML 写入时设置line_width: -1不自动换行见第 43-46 行。normalize -p变体可强制按规则搬移键。4.check-consistent-interpolations校验插值一致性检查同一个键在不同语言中的插值占位符如%{name}、%{descendants}是否一致。若英文写作%{name}: %{description}见 config/locales/en.yml 中accessibility.macro.aria_label_with_name而某语言漏掉%{description}运行时就会出现KeyError或渲染异常该命令在 CI/提交前拦截这类问题。如确有例外可配置ignore_inconsistent_interpolations。提示i18n-tasks 本身也在 config/i18n-tasks.yml 中通过PatternMapper注册了自定义扫描器用来识别项目特有的link_translate(some.key, ...)辅助方法调用——这类调用因未走标准t()/I18n.t()而无法被默认扫描器捕获。这意味着项目内所有翻译入口都纳入了同一套静态检查体系。五、运行时兜底复数化与回退机制翻译键的正确性不仅依赖静态检查还依赖运行时的健壮性设计。config/initializers/i18n.rb 展示了两个关键增强复数化兜底加载lib/open_project/translations/pluralization_backend.rb定义的PluralizationBackend并include进I18n::Backend::Simple。该模块pluralization_backend.rb覆写pluralize方法当俄语、匈牙利语、波兰语等东欧语言缺少:many复数键触发I18n::InvalidPluralizationData异常时安全回退到:other键若无:other则返回 nil表现为“缺失翻译”而不是直接抛异常——避免单个语言文件缺陷拖垮整个请求默认语言回退include I18n::Backend::Fallbacks为未翻译的字符串回退到默认语言base_locale: en。注释特别指出管理员配置的邮件头/邮件尾Setting#localized_emails_header/Setting#localized_emails_footer可能未提供所有语言版本必须依赖该回退机制。六、前端 JS 翻译从 YAML 到 JSON 的自动化管线OpenProject 的 Angular 前端同样使用翻译键其英文源为 config/locales/js-en.yml而输出映射规则定义在 config/i18n.yml注意该文件只控制前端 i18n-js 的翻译embed_fallback_translations: enabled: true translations: - file: frontend/src/locales/:locale.json patterns: - *.js.* - *.number.* - *.time.* - *.date.*即只有js.*、number.*、time.*、date.*四类命名空间的键会被打包进前端产物 frontend/src/locales/并以locale.json形式输出且启用回退翻译嵌入。config/initializers/i18n-js.rb 进一步说明开发模式下应用启动后会调用I18nJS.listen持续监听根目录config/locales及所有模块的**/config/locales目录翻译文件一有改动即自动重建 JS 翻译实现热更新式的前端多语言开发体验frontend/src/locales/README.md 也说明该目录存放开发/生产环境生成的翻译并指向项目翻译贡献指南。七、提交前检查清单结合上述约定一个完整的“新增 UI 文案”开发流程应为在对应模块或根目录的config/locales/en.yml中添加英文键如some_feature.title: ...运行bundle exec i18n-tasks missing确认代码中引用的键已全部登记运行bundle exec i18n-tasks normalize归一化文件结构运行bundle exec i18n-tasks check-consistent-interpolations校验插值一致性运行bundle exec i18n-tasks unused清理废弃键将新英文键通过 crowdin.yml 同步到 Crowdin 平台等待社区译者补充各语言翻译前端若需要显示该文案确认键位于js.*等白名单命名空间开发模式下由监听进程自动产出frontend/src/locales/:locale.json。结语OpenProject 的国际化并非零散地“在代码里写字符串”而是一套从“禁止硬编码”的编码规范、en.yml源文件与 Crowdin 协作分工、i18n-tasks静态检查到复数化与回退兜底、前端 JSON 自动生成的完整工程体系。理解 config/AGENTS.md 这份简短约定背后的实现细节能帮助贡献者以最低成本、最高质量地向这一多语言开源项目提交翻译相关改动。【免费下载链接】openprojectOpenProject is the leading open source project management software for product, project and portfolio management. A powerful Jira alternative with agile planning, issue tracking, roadmaps, Gantt charts, time tracking, collaboration features, and more. Available on premises or in the cloud. ⭐ Star us on GitHub项目地址: https://gitcode.com/GitHub_Trending/op/openproject创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 OpenProject 配置目录国际化规范：i18n-tasks 工作流与 Crowdin 翻译管理实战
OpenProject 配置目录国际化规范i18n-tasks 工作流与 Crowdin 翻译管理实战【免费下载链接】openprojectOpenProject is the leading open source project management software for product, project and portfolio management. A powerful Jira alternative with agile planning, issue tracking, roadmaps, Gantt charts, time tracking, collaboration features, and more. Available on premises or in the cloud. ⭐ Star us on GitHub项目地址: https://gitcode.com/GitHub_Trending/op/openproject导读OpenProject 作为覆盖项目管理、敏捷看板与组合管理的开源软件其界面文本支持数十种语言而这背后是一套严格的“配置目录国际化i18n规范”。本文以仓库config/目录下的 AGENTS.md 约定为骨架系统讲解 OpenProject 的翻译键约束、en.yml源文件编辑方式、Crowdin 社区翻译协作流程以及i18n-tasks四个核心 CLI 命令的用法与底层原理并结合仓库源码说明前端 JS 翻译、复数化兜底等关键实现帮助开发者在参与 OpenProject 开发或自建多语言功能时快速上手。一、总体约定UI 字符串必须走翻译键config/AGENTS.md首先确立了一条铁律UI strings must use translation keys (never hard-coded)即界面字符串一律使用翻译键translation key严禁硬编码。这条约束在仓库中随处可见视图层通过t(...)/I18n.t(...)取键例如 app/components/admin/backups/reset_token_dialog_component.html.erb 中的按钮文案组件层则在 Ruby 中调用I18n.t。如此设计的目标是让“文本”与“逻辑”彻底解耦任何新增的 UI 文案都必须在英文源文件中登记一个键再由各语言文件提供对应翻译从而保证语言切换、复数规则、无障碍标签等能力的一致性。在组件开发层面OpenProject 对 ViewComponent 的惰性查找lazy lookup做了专门适配。app/components/translations_override.rb 注释解释了原因由于项目未使用 ViewComponent 自带的 sidecar 翻译文件VC 4.0 的#translate会转发到I18n.translate而项目依赖 ActionView 的覆盖实现来支持组件内的惰性键解析因此该模块显式include ActionView::Helpers::TranslationHelper。这意味着组件内的t(.some_key)相对键能够按“组件路径 方法名”正确解析参见 config/i18n-tasks.yml 中关于relative_roots与relative_exclude_method_name_paths的配置。二、英文源文件可以直接修改的en.yml文档规定源翻译存放在**/config/locales/en.yml中可以直接修改。这里的**通配符覆盖两层含义核心仓库config/locales/en.yml 是主英文翻译文件包含约 6000 余条键覆盖 accessibility、activerecord、work_package、project 等全部命名空间各功能模块OpenProject 以模块化方式组织代码29 个模块各自维护独立的config/locales/en.yml例如 modules/storages/config/locales/en.yml文件存储模块、modules/meeting/config/locales/en.yml 等。这也是 config/i18n-tasks.yml 中data.read读取来源的一部分。因此新增或修改英文文案时先定位该功能所属的模块目录再编辑对应en.yml根目录的config/locales/en.yml则承载核心应用文案。三、其他语言统一交给 Crowdin 管理与英文源文件不同其他语言的翻译统一由 Crowdin 管理开发者不应手工编辑config/locales/crowdin/下的 165 个语言文件涵盖 af、ar、az、de、fr、ja、zh 等。仓库 crowdin.yml 定义了与 Crowdin 平台的同步配置这一工作流带来的收益是翻译由社区译者分布式完成且版本回退、词条一致性检查都在平台侧完成。仓库中与 Crowdin 配套的脚本位于 script/i18n/generate_seeders_i18n_source_file把种子数据seeds中的默认内容如颜色名、默认状态名抽成可翻译的源文件文件头明确标注“This file has been generated … Please do not edit directly”见 config/locales/crowdin/de.seeders.ymlrewrite_crowdin_yml_files/fix_crowdin_pt_language_root_key处理 Crowdin 下载产物中的键根节点等格式问题generate_languages_translations基于 CLDR 数据代码中CLDR_VERSION 44生成本地化语言元数据test_seed_all_locales批量校验所有语言环境下种子数据的可加载性。此外config/locales/generated/存放生成产物en.yml、de.yml等按语言聚合的文件config/locales/js-en.yml 则是前端 JS 用的英文翻译源。整体目录分工可归纳为目录/文件角色编辑方式**/config/locales/en.yml英文源翻译含各模块开发者直接修改config/locales/crowdin/*.yml各语言社区翻译仅通过 Crowdin 平台config/locales/generated/*.yml生成/聚合产物脚本生成勿手改config/locales/js-*.yml前端 JS 翻译源按需更新英文源四、i18n-tasks 四件套检查、清理与归一化文档给出了开发者在提交翻译改动前必须运行的四个命令全部基于i18n-tasks这个 Ruby gem依赖声明见 Gemfile版本约束为~ 1.1.0require: false按需加载bundle exec i18n-tasks missing # Show missing translation keys bundle exec i18n-tasks unused # Show unused translation keys bundle exec i18n-tasks normalize # Fix/normalize translation files bundle exec i18n-tasks check-consistent-interpolations # Check interpolation consistency1.missing找出缺失的翻译键扫描代码中所有翻译调用对照各语言文件找出缺失的键。工具的搜索范围与规则在 config/i18n-tasks.yml 中定义search.paths默认搜索app/当前配置额外加入了modules/storages/app/模块内代码同样纳入检查exclude排除app/assets/images、app/assets/fonts、app/assets/videos、app/assets/builds等非代码资源目录strict模式默认 true下t(categories.#{category}.title)这类动态拼接会被识别为“猜测用法”从而避免误报。2.unused找出未使用的翻译键用于发现已被代码移除、但仍残留在语言文件中的键。为避免误报config/i18n-tasks.yml 配置了ignore_unused白名单例如ignore_unused: - activerecord.{models,attributes,errors}.* - permission_* - {devise,kaminari,will_paginate}.* - *.permission_header_explanation - storages.upsell.* - services.* - storages.health.checks.*这些键要么由 Rails 框架按约定动态查找如activerecord.attributes.*对应User.human_attribute_name(:email)要么由权限/服务等反射式机制使用静态扫描无法定位因此需要显式豁免。3.normalize归一化翻译文件对 YAML 文件做排序、键结构调整保证多语言文件结构一致避免合入 Crowdin 后产生大量无意义 diff。归一化遵循 config/i18n-tasks.yml 的data.write路由规则例如 storages 模块的键会被强制写入modules/storages/config/locales/%{locale}.yml其余键走config/locales/%{locale}.yml的 catch-all 规则YAML 写入时设置line_width: -1不自动换行见第 43-46 行。normalize -p变体可强制按规则搬移键。4.check-consistent-interpolations校验插值一致性检查同一个键在不同语言中的插值占位符如%{name}、%{descendants}是否一致。若英文写作%{name}: %{description}见 config/locales/en.yml 中accessibility.macro.aria_label_with_name而某语言漏掉%{description}运行时就会出现KeyError或渲染异常该命令在 CI/提交前拦截这类问题。如确有例外可配置ignore_inconsistent_interpolations。提示i18n-tasks 本身也在 config/i18n-tasks.yml 中通过PatternMapper注册了自定义扫描器用来识别项目特有的link_translate(some.key, ...)辅助方法调用——这类调用因未走标准t()/I18n.t()而无法被默认扫描器捕获。这意味着项目内所有翻译入口都纳入了同一套静态检查体系。五、运行时兜底复数化与回退机制翻译键的正确性不仅依赖静态检查还依赖运行时的健壮性设计。config/initializers/i18n.rb 展示了两个关键增强复数化兜底加载lib/open_project/translations/pluralization_backend.rb定义的PluralizationBackend并include进I18n::Backend::Simple。该模块pluralization_backend.rb覆写pluralize方法当俄语、匈牙利语、波兰语等东欧语言缺少:many复数键触发I18n::InvalidPluralizationData异常时安全回退到:other键若无:other则返回 nil表现为“缺失翻译”而不是直接抛异常——避免单个语言文件缺陷拖垮整个请求默认语言回退include I18n::Backend::Fallbacks为未翻译的字符串回退到默认语言base_locale: en。注释特别指出管理员配置的邮件头/邮件尾Setting#localized_emails_header/Setting#localized_emails_footer可能未提供所有语言版本必须依赖该回退机制。六、前端 JS 翻译从 YAML 到 JSON 的自动化管线OpenProject 的 Angular 前端同样使用翻译键其英文源为 config/locales/js-en.yml而输出映射规则定义在 config/i18n.yml注意该文件只控制前端 i18n-js 的翻译embed_fallback_translations: enabled: true translations: - file: frontend/src/locales/:locale.json patterns: - *.js.* - *.number.* - *.time.* - *.date.*即只有js.*、number.*、time.*、date.*四类命名空间的键会被打包进前端产物 frontend/src/locales/并以locale.json形式输出且启用回退翻译嵌入。config/initializers/i18n-js.rb 进一步说明开发模式下应用启动后会调用I18nJS.listen持续监听根目录config/locales及所有模块的**/config/locales目录翻译文件一有改动即自动重建 JS 翻译实现热更新式的前端多语言开发体验frontend/src/locales/README.md 也说明该目录存放开发/生产环境生成的翻译并指向项目翻译贡献指南。七、提交前检查清单结合上述约定一个完整的“新增 UI 文案”开发流程应为在对应模块或根目录的config/locales/en.yml中添加英文键如some_feature.title: ...运行bundle exec i18n-tasks missing确认代码中引用的键已全部登记运行bundle exec i18n-tasks normalize归一化文件结构运行bundle exec i18n-tasks check-consistent-interpolations校验插值一致性运行bundle exec i18n-tasks unused清理废弃键将新英文键通过 crowdin.yml 同步到 Crowdin 平台等待社区译者补充各语言翻译前端若需要显示该文案确认键位于js.*等白名单命名空间开发模式下由监听进程自动产出frontend/src/locales/:locale.json。结语OpenProject 的国际化并非零散地“在代码里写字符串”而是一套从“禁止硬编码”的编码规范、en.yml源文件与 Crowdin 协作分工、i18n-tasks静态检查到复数化与回退兜底、前端 JSON 自动生成的完整工程体系。理解 config/AGENTS.md 这份简短约定背后的实现细节能帮助贡献者以最低成本、最高质量地向这一多语言开源项目提交翻译相关改动。【免费下载链接】openprojectOpenProject is the leading open source project management software for product, project and portfolio management. A powerful Jira alternative with agile planning, issue tracking, roadmaps, Gantt charts, time tracking, collaboration features, and more. Available on premises or in the cloud. ⭐ Star us on GitHub项目地址: https://gitcode.com/GitHub_Trending/op/openproject创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考