Yii 2 翻译工作流完全指南：框架消息提取、文档翻译与国际化协作实践

后端Web框架【免费下载链接】yii2Yii 2: The Fast, Secure and Professional PHP Framework项目地址https://gitcode.com/gh_mirrors/yi/yii2点击查看免费下载导读Yii 2 作为面向国际化的 PHP 框架其核心代码、校验器与框架消息均内置了多语言支持同时官方文档也被翻译为十余种语言。本文以 docs/internals-sr-Latn/translation-workflow.md 为核心脉络系统讲解 Yii 2 框架消息framework messages的提取、翻译与维护流程以及文档翻译的目录约定和差异报告生成方法并结合仓库内 framework/messages/config.php、framework/console/controllers/MessageController.php 等源码与真实翻译文件深入剖析底层实现原理。读完本文你将能够为 Yii 2 新增一种语言的消息翻译、把官方文档翻译到目标语言并通过构建命令自动生成翻译进度报告。翻译贡献的两大领域Yii 2 的国际化工作覆盖两个主要区域二者贡献者都可以直接参与框架消息framework messages指框架内通过Yii::t()定义的、会展示给最终用户的字符串例如表单校验错误提示。文档documentation指 docs/guide用户指南、docs/internals内部文档等官方文档的多语言翻译。一个重要的前提是并非所有框架内字符串都需要翻译。Yii 2 框架中存在两类消息面向开发者的异常消息例如Invalid config value for the ... component这类抛给程序员的异常文本永远不会被翻译保持英文原样面向最终用户的可见消息例如The file {file} is too big.、Page not found.、Please fix the following errors:等校验与界面提示这些才是翻译工作的对象。判断标准很简单凡是通过Yii::t(yii, ...)翻译函数标记的、实际渲染到页面上的消息都属于需要翻译的范畴。框架消息翻译四步流程第 1 步在languages列表中登记你的语言打开 framework/messages/config.php检查你的语言代码是否已存在于languages数组中languages [ af, ar, az, be, bg, bs, ca, cs, da, de, el, es, et, fa, fi, fr, ga, he, hi, pt-BR, ro, hr, hu, hy, id, it, ja, ka, kk, ko, kz, lt, lv, ms, mt, nb-NO, nl, pl, pt, ru, sk, sl, sr, sr-Latn, sv, tg, th, tr, uk, uz, uz-Cy, vi, zh, zh-TW ],如果目标语言不在列表中就添加它并保持列表的字母顺序。语言代码的书写格式必须遵循IETF 语言标签规范IETF language tag spec例如ru俄语zh-CN简体中文地区子标签使用连字符分隔sr-Latn塞尔维亚语拉丁字母变体仓库实际维护的语言目录可参见 framework/messages 下的各语言子目录af/、ru/、sr-Latn/、zh/、zh-TW/等当前共计五十余种与config.php的languages列表一一对应。第 2 步运行消息提取命令进入framework目录执行控制台命令./yii message/extract yii/messages/config.php --languagesyour_language其中your_language替换为目标语言代码例如./yii message/extract yii/messages/config.php --languageszh-CN该命令由 framework/console/controllers/MessageController.php 的actionExtract()实现其底层执行流程为initConfig()读取配置文件校验必须包含sourcePath与languages两个键对应源码第 984-985 行的throw new Exception(The configuration file must specify sourcePath and languages.)通过FileHelper::findFiles()遍历 framework 目录下所有符合only [*.php]规则、且未被except排除的 PHP 源文件使用配置中的translator [\Yii::t, Yii::t]作为标记正则扫描每个文件中Yii::t(...)的调用array_merge_recursive汇总出全部待翻译消息对配置中列出的每个语言在messagePath即framework/messages下创建language子目录并调用saveMessagesToPHP()写入翻译文件。actionExtract()还支持format配置为db写入数据库表{{%source_message}}/{{%message}}或po/pot生成 GNU gettext 格式但框架自身的消息翻译默认使用php格式。第 3 步翻译消息文件命令执行后会在 framework/messages/your_language/yii.php 生成或更新翻译文件。务必确保文件以 UTF-8 编码保存文件头注释也明确写有NOTE: this file must be saved in UTF-8 encoding.。翻译文件的格式为 PHP 数组每个数组元素就是一条消息的键值对键是英文原文值是该消息的翻译。以 framework/messages/sr-Latn/yii.php 为例return [ and i , (not set) (bez vrednosti), An internal server error occurred. Došlo je do interne greške na serveru., Delete Obriši, Home Početna, Page not found. Stranica nije pronađena., The file {file} is too big. Its size cannot exceed {formattedLimit}. Fajl {file} je prevelik. Veličina ne može biti veća od {formattedLimit}., // ... ];翻译时有几个关键约定值为空串表示未翻译例如Action not found. 表示这条消息尚未翻译提取命令再次运行时会保留空值待后续填充双标记表示已废弃消息在源码中不再出现removeUnused与markUnused均为true时其翻译会被包裹在一对之间例如... 翻译文本提示该条目已不再需要翻译若配置removeUnused true则会直接删除这类条目见 framework/messages/config.php 第 33-38 行的注释说明支持复数形式格式plural forms消息字符串可以使用 ICU 复数语法例如 framework/messages/sr-Latn/yii.php 中的分页提示Showing b{begin, number}-{end, number}/b of b{totalCount, number}/b {totalCount, plural, one{item} other{items}}. Prikazano b{begin, number}-{end, number}/b od b{totalCount, number}/b {totalCount, plural, 1{stavke} one{stavke} few{stavke} many{stavki} other{stavki}}.,复数规则1、one、few、many、other与目标语言自身的语法体系强相关——例如塞尔维亚语同时存在few少量与many大量规则而中文几乎只需other。关于复数格式与消息占位符{begin, number}、{totalCount, plural, ...}的完整语法请参考 i18n 章节 的教程。第 4 步提交 Pull Request完成翻译后按照 docs/internals-sr-Latn/git-workflow.md 描述的 Git 工作流提交 Pull Request 即可。值得一提的是该文档指出仅涉及翻译字符串、文档或 JS/CSS/图片的改动会在提交信息中加入[ci skip]标记从而跳过 CI 构建以减轻服务负担——纯翻译提交因此通常无需等待完整测试流水线。保持翻译与源码同步源码迭代后消息集可能发生变化新增消息、删除消息。此时只需再次运行同一条提取命令./yii message/extract yii/messages/config.php --languagesyour_language提取器会自动合并差异已翻译且仍被使用的消息原样保留新增的消息以空值追加不再需要的消息则被标记或删除取决于配置。这正是 framework/messages/config.php 中overwrite true、sort true、removeUnused true、markUnused true等选项协同作用的结果贡献者无需手工比对源码与翻译文件的差异。配置文件关键参数速览framework/messages/config.php 是消息提取的枢纽其核心参数与作用如下参数当前仓库取值作用说明sourcePath__DIR__ . /..即 framework 根目录扫描哪些目录下的源码以提取Yii::t()消息messagePath__DIR__framework/messages生成的翻译文件存放根目录languages五十余种语言代码数组需要生成/更新哪些语言的翻译文件translator[\Yii::t, Yii::t]以哪些函数调用作为消息提取标记sorttrue合并新消息时是否按键排序overwritetrue是否用合并结果覆盖现有翻译文件removeUnusedtrue是否删除源码中已不存在的消息条目markUnusedtrue是否用标记已不存在的消息与removeUnused配合使用except[.*, /.*, /messages, /tests, /runtime, /vendor, /BaseYii.php]排除不参与提取的目录/文件如 tests、vendoronly[*.php]仅处理 PHP 源文件formatphp输出格式可改为db、po、potphpFileHeaderYii 标准版权头注释写入生成文件的头部注释从源码看MessageController.phpformat决定消息落盘方式php/po按语言逐目录写文件db写入数据库两张表pot生成单一 POT 模板。若自行扩展提取场景可参考该文件生成符合需求的自定义配置。文档翻译目录约定与进度报告目录结构约定文档翻译与消息翻译的存放方式不同所有文档翻译统一放在docs/original-language目录下其中original是原始文档集的名称例如guide用户指南或internals内部文档language是目标文档的语言代码。例如俄语用户指南的翻译位于 docs/guide-ru而本文所属的塞尔维亚语拉丁字母版内部文档位于 docs/internals-sr-Latn。仓库中现存的语言版本包括guide-ar、guide-de、guide-es、guide-fr、guide-id、guide-it、guide-ja、guide-pl、guide-pt-BR、guide-ru、guide-tr、guide-uk、guide-uz、guide-vi、guide-zh-CN等均遵循同一命名规则。生成翻译进度报告文档翻译的难点在于追踪上次翻译之后源文档又改了什么。仓库为此提供了专门的构建命令在build目录下执行php build translation ../docs/guide ../docs/guide-ru Russian guide translation report report_guide_ru.html该命令接收三个参数../docs/guide原始文档目录英文版../docs/guide-ru目标语言翻译目录Russian guide translation report生成报告 HTML 页面的标题文字。输出通过 shell 重定向写入report_guide_ru.html打开即可查看源文档中尚未同步到翻译版的变更内容。如果命令提示缺少 composer 依赖先在仓库根目录执行composer install再重试。文档写作规范翻译文档同样需要遵守官方写作规范可参考 docs/documentation_style_guide.md 中的语法与排版指南如代码块、链接、表格的使用约定保证翻译文档与英文原版在结构上保持一致便于后续差异比对工具准确识别变更。结合源码理解消息提取的底层逻辑想要透彻理解翻译工作流可以通读消息提取控制器的核心实现 framework/console/controllers/MessageController.phpactionExtract()第 300-341 行提取主入口遍历源码 → 聚合消息 → 按format分发到不同保存逻辑actionConfig()相关逻辑第 65、168、198 行--languages命令行选项映射到$this-languages覆盖配置文件中的同名键这正是--languagesyour_language能按需限定目标语言的原因saveMessagesToPHP()负责php格式文件的合并写入实现保留已翻译条目、追加新条目、标记废弃条目的合并语义第 984-985 行的配置校验配置文件缺少sourcePath或languages时直接抛出异常避免误用不完整配置。对框架自身的消息提取而言sourcePath指向 framework 根目录translator标记Yii::t(yii, ...)形式的调用except规则排除了tests、vendor、runtime以及BaseYii.php其内部含大量仅供开发者阅读的异常消息不应进入翻译流程。这与文档中开发者异常不翻译、用户可见消息才翻译的原则相互印证。实战检查清单完成一次框架消息翻译贡献可按以下清单自检语言代码已按字母顺序加入 framework/messages/config.php 的languages列表且符合 IETF 标签规范如zh-CN、sr-Latn在framework目录下成功执行./yii message/extract yii/messages/config.php --languagesyour_language生成了framework/messages/language/yii.php翻译文件已用 UTF-8 编码保存空值消息已填充译文标记的废弃消息已按需处理涉及复数或占位符的消息严格遵循 i18n 教程 的格式如{totalCount, plural, one{...} other{...}}文档翻译位于docs/original-language目录必要时用php build translation生成报告核对同步进度按 Git 工作流 提交 Pull Request纯翻译改动可在提交信息中包含[ci skip]。遵循上述流程无论是为 Yii 2 补齐一个新语种的框架消息还是推进某语言版本的官方文档翻译都能在清晰的目录约定与自动化的提取/报告工具支持下高效完成让框架真正服务于国际化的应用与开发者。赞分享后端Web框架【免费下载链接】yii2Yii 2: The Fast, Secure and Professional PHP Framework项目地址https://gitcode.com/gh_mirrors/yi/yii2点击查看免费下载相关推荐3大技术突破OpenHantek如何为开源示波器软件定义新标准3大技术突破OpenHantek如何为开源示波器软件定义新标准 你是否曾经面对昂贵的专业示波器软件而感到无力或者在使用闭源硬件时受限于厂商提供的有限功能O桌面应用智能硬件Yii 2 国际化I18N完全指南消息翻译、ICU 格式化与 message 命令实战Yii 2 国际化I18N完全指南消息翻译、ICU 格式化与 message 命令实战 本指南基于 Yii 2 框架的官方国际化文档 docs/guid后端Web框架focus.nvim高级技巧如何利用方向键实现智能窗口分割与导航focus.nvim高级技巧如何利用方向键实现智能窗口分割与导航 作为一名 Neovim 用户你是否厌倦了手动调整窗口大小的繁琐操作是否希望在多个分割窗口上一篇抖音视频批量采集助手3步掌握多用户视频高效下载终极指南下一篇WarcraftHelper3分钟解决魔兽争霸III现代系统兼容性问题创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考