PHP注释需遵循国际协作规范：单行/多行注释统一用英文，禁用中文；PHPDoc须严格按PSR-5标准，含准确@param、@return等标签；国际化相关注释应说明locale行为而非翻译内容；注释需支持工具链自动化处理。
PHP注释本身不涉及国际化（i18n），但注释的**内容撰写规范**和**文档注释结构**需符合国际协作惯例，才能让全球开发者快速理解代码逻辑。关键不在“翻译注释”，而在用标准语法、清晰术语、统一风格写注释，尤其在开源项目中。
单行与多行注释：用英文写，禁用中文或拼音缩写
开源项目默认要求所有非文档类注释使用英文，这是跨团队协作的基础。即使你面向中文用户开发，也应遵守这一惯例。
- // ✅ 正确：// Validate email format before saving
- // ❌ 避免：// 验证邮箱格式 // 或 // yzm_yz
- /* ... */ 中同样不混入中文，避免 Git 差异混乱或 IDE 解析异常
- 临时屏蔽代码可用 /* ... */，但上线前必须清理，不可留调试型中文注释
PHPDoc 文档注释：严格遵循 PSR-5（现为 PHP-FIG 推荐标准）
函数、类、方法、属性前的 /** ... */ 注释不是可选项，而是开源项目的“接口说明书”。它支撑 IDE 提示、静态分析（如 PHPStan）、自动生成文档（如 phpDocumentor）。
- 必须以 /** 开头（两个星号），结尾为 */
- @param 类型必须准确：@param string $email 而非 @param $email（缺类型）或 @param str $email（非标准）
- @return 明确标注 null、false、void 等边界情况：@return User|null
- 支持 @throws、@see、@deprecated 等标签，增强可维护性
国际化相关代码处，注释要说明 locale 行为而非翻译文本
当使用 gettext、intl 或语言包时，注释重点不是“这句话译成什么”，而是“这个字符串如何被提取/切换/回退”。
立即学习“PHP免费学习笔记（深入）”；
- ✅ 好注释：// Translatable via gettext domain 'frontend'; fallback to 'en_US' if missing
- ✅ 好注释：// Uses ResourceBundle::get() — ensure 'messages' bundle is loaded for current locale
- ❌ 避免：// 这里显示“欢迎” → 实际翻译由 .mo 文件控制，注释无需重复
- 敏感字段（如密码提示语）建议加注：// Not translatable — hardcoded for security audit trail
工具链协同：注释要能被自动化流程识别
真正接轨国际，是让注释成为 CI/CD 和协作流程的一环：
- 用 php-cs-fixer 或 PHP_CodeSniffer 配置规则，强制 @param/@return 不缺失
- CI 中加入 phpdocumentor 构建检查，确保文档注释语法合法
- po 文件提取脚本（如 xgettext）依赖源码中 _("Login") 这类调用，其旁注释可写：// TRANSLATORS: button label on auth page
- IDE 如 PhpStorm 或 VS Code + intelephense 会读取 PHPDoc 生成悬停提示，写得准，体验就强
