前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载导读本文讲解 wp-calypso 仓库中eslint-plugin-wpcalypso插件的i18n-translate-identifier规则它强制要求引用翻译函数的变量标识符与翻译函数原名保持一致translate或__/_n/_nx/_x否则会报错。规则背后的原因是 WordPress.com 的字符串提取工具基于静态代码分析只会识别特定标识符下的字符串。读完本文你将掌握该规则的检测范围、违规与合规写法、底层实现原理以及如何在项目中启用它。规则为什么存在字符串提取依赖静态分析Calypso 项目的国际化i18n流程中所有可翻译字符串最终都要经过字符串提取工具string extraction tools扫描源码生成可供翻译人员工作的词条文件。这些工具本质上是静态代码分析器——它们不执行代码而是通过语法层面的模式匹配去查找translate()、__( ... )这类函数调用。这意味着如果翻译函数的调用点使用了别名的变量名提取工具就看不见这些字符串。例如下面这段代码__确实指向了翻译函数但提取工具只会扫描__开头的调用const t useTranslate(); t( Hello world ); // 提取工具无法识别 t(...)该字符串不会被提取因此i18n-translate-identifier规则要求声明指向翻译函数的变量时标识符必须与翻译函数的原始名称一致——i18n-calypso对应translatewordpress/react-i18n底层为wordpress/i18n对应__、_n、_nx、_x。规则定义见 i18n-translate-identifier.md源码实现见 i18n-translate-identifier.js。规则覆盖的两类调用场景从实现上看该规则只关注两个 calleeuseTranslate和useI18n。它们分别对应 Calypso 体系中两种主流的 React 国际化 hook来源库Hook允许的变量名说明automattic/i18n-calypso仓库中位于 packages/i18n-calypsouseTranslate()translate单个返回值直接赋值给变量wordpress/react-i18n/wordpress/i18nuseI18n()__、_n、_nx、_x对象返回值通过解构ObjectPattern取属性对应的常量定义在实现文件顶部const I18N_CALYPSO_TRANSLATE_FUNCTION translate; const WP_I18N_TRANSLATE_FUNCTIONS new Set( [ __, _n, _nx, _x ] );值得一提的是useTranslate的真实返回就是一个绑定了 i18n 实例的translate函数见 packages/i18n-calypso/src/use-translate.js所以变量名必须叫translate在语义上也是自洽的。哪些写法会被判定为警告warning以下模式来自原文档均会被规则报告场景一useTranslate返回值赋给非translate的变量名const __ useTranslate(); const t useTranslate();场景二从useI18n()解构翻译函数但重命名了标识符const { __: translate } useI18n(); const { _nx: _n } useTranslate();第二条值得注意文档示例中混用了useI18n与useTranslate来演示重命名即报错这一核心逻辑实际触发检查的是解构属性key是否属于允许集合以及key.name与value.name是否不一致。哪些写法是合规的non-warning场景一useTranslate返回值直接命名为translateconst translate useTranslate();场景二从useI18n()解构且不重命名const { __ } useI18n(); const { _n } useI18n(); const { _nx } useI18n(); const { _x } useI18n(); const { __, _n, _nx, _x } useI18n();边界情况与更多验证样本原文档之外规则配套的测试文件 lib/rules/test/i18n-translate-identifier.js 提供了更完整的判例可以帮助你精确理解检测边界合法validvar translate useTranslate(); const translate useTranslate(); let translate useTranslate(); useTranslate(); // 裸调用无变量声明不检测 const { isRTL } useI18n(); // 解构非翻译函数属性如 isRTL不检测 useI18n(); // 裸调用无变量声明不检测非法invalid及对应报错信息代码报错内容节选const __ useTranslate();Variable identifier should be named \translate ...const { __: translate } useI18n();... named \__ ...const { _nx: _n } useI18n();... named \_nx ...const { __, _n: translate } useI18n();... named \_n ...const { __: a, _n: b, _nx: c, _x: d } useI18n();依次报 4 条分别要求命名为__/_n/_nx/_x从中可以提炼出三条判定规则若声明的是useTranslate()的结果标识符必须精确等于translatevar/const/let均适用若从useI18n()解构出__/_n/_nx/_x之一不允许重命名key.name ! value.name即报错解构出来的非翻译函数属性如isRTL不受约束裸调用useTranslate()/useI18n()也不受约束。测试中还展示了错误消息模板Variable identifier should be named \{{translateFnName}} in order to be properly detected by the string extraction tools其中{{translateFnName}}会被替换为期望的原始函数名对应实现中的rule.ERROR_MESSAGE与data.translateFnName。深入实现规则是如何工作的规则的实现非常精简核心是一个监听CallExpression的处理器i18n-translate-identifier.js大致分为两个分支分支一useTranslate场景通过getCallee( node ).name useTranslate判定调用检查其父节点是否为VariableDeclarator且声明标识符存在若node.parent.id.name ! translate在声明标识符节点上报告错误。分支二useI18n场景判定 callee 为useI18n且父节点是VariableDeclarator进一步要求声明标识符类型为ObjectPattern即const { ... } useI18n()这种解构写法遍历properties仅当属性的key.name属于WP_I18N_TRANSLATE_FUNCTIONS且与value.name不一致时报告value就是解构后引入的本地变量名这也是const { __: a }重命名被识别的原因。callee 解析工具getCallee规则依赖的工具函数 lib/util/get-callee.js 会递归处理两类特殊情况SequenceExpression逗号表达式时取最后一个表达式MemberExpression时取属性部分支持obj.useTranslate()这类写法。此外规则还暴露了schema []表示它不接受任何配置选项属于零配置、即插即用的规则。如何在项目中启用该规则eslint-plugin-wpcalypso的推荐配置已经默认开启了这条规则recommended.js 中wpcalypso/i18n-translate-identifier: error所以最简单的做法是直接在.eslintrc中继承推荐配置{ extends: [ plugin:wpcalypso/recommended ] }React 项目也可以继承更完整的plugin:wpcalypso/react配置见 react.js它内部先扩展了 recommended再叠加 react/react-hooks 相关规则。如果只想单独启用这一条规则则先注册插件、再按需配置{ plugins: [ wpcalypso ], rules: { wpcalypso/i18n-translate-identifier: error } }安装方式与完整规则清单可参考 eslint-plugin-wpcalypso/README.mdyarn add --dev eslint eslint-plugin-wpcalypso与同族 i18n 规则的关系i18n-translate-identifier只是 Calypso 国际化 ESLint 规则家族中的一员。推荐配置里与翻译字符串相关的还有全部定义在 docs/rules 下i18n-ellipsis禁止在可翻译字符串中使用三个点号i18n-mismatched-placeholders确保单复数字符串的占位符数量一致i18n-named-placeholders禁止多个未命名占位符i18n-no-collapsible-whitespace禁止可翻译字符串中的可折叠空白i18n-no-placeholders-only禁止只包含占位符的字符串i18n-no-this-translate禁止this.translate()i18n-no-variables禁止用变量作为 translate 字符串i18n-unlocalized-url禁止未本地化的 URL。这一组规则从调用形式、标识符命名、字符串内容三个层面共同保障了提取管线能够稳定、完整地收获所有待翻译文案。i18n-translate-identifier负责的是其中最基础的一环——确保翻译函数的调用点以提取工具认识的名字出现。你在实际项目中可以先跑一遍eslint --fix或yarn lint让这条规则在 CI 阶段就拦截掉改名引入的漏翻译问题避免上线后出现未本地化的英文文案。赞分享前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载相关推荐wp-calypso i18n 规则 i18n-named-placeholders 深度解析为什么多个占位符必须命名ESLint 如何静态拦截wp calypso i18n 规则 i18n named placeholders 深度解析为什么多个占位符必须命名ESLint 如何静态拦截 本文以 e前端CMSwp-calypso 国际化规范ESLint 规则 i18n-no-variables 禁止变量作为 translate() 翻译字符串的完整解析wp calypso 国际化规范ESLint 规则 i18n no variables 禁止变量作为 translate 翻译字符串的完整解析 导读 在 Wo前端CMS音频解密终极指南如何免费解锁12种加密音乐格式音频解密终极指南如何免费解锁12种加密音乐格式 你是否曾经购买过数字音乐却发现只能在特定播放器上收听或者当你更换设备时那些精心收藏的音乐文件突然无法播放前端CMS上一篇如何快速掌握BepInEx面向游戏爱好者的终极插件框架指南下一篇GHelper完整指南华硕笔记本终极性能控制与硬件优化方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 
长河君 · 2026/10/9 1:22:00 · 阅读 1.2k wp-calypso 的 i18n-translate-identifier ESLint 规则：为什么翻译函数变量名必须严格一致
前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载导读本文讲解 wp-calypso 仓库中eslint-plugin-wpcalypso插件的i18n-translate-identifier规则它强制要求引用翻译函数的变量标识符与翻译函数原名保持一致translate或__/_n/_nx/_x否则会报错。规则背后的原因是 WordPress.com 的字符串提取工具基于静态代码分析只会识别特定标识符下的字符串。读完本文你将掌握该规则的检测范围、违规与合规写法、底层实现原理以及如何在项目中启用它。规则为什么存在字符串提取依赖静态分析Calypso 项目的国际化i18n流程中所有可翻译字符串最终都要经过字符串提取工具string extraction tools扫描源码生成可供翻译人员工作的词条文件。这些工具本质上是静态代码分析器——它们不执行代码而是通过语法层面的模式匹配去查找translate()、__( ... )这类函数调用。这意味着如果翻译函数的调用点使用了别名的变量名提取工具就看不见这些字符串。例如下面这段代码__确实指向了翻译函数但提取工具只会扫描__开头的调用const t useTranslate(); t( Hello world ); // 提取工具无法识别 t(...)该字符串不会被提取因此i18n-translate-identifier规则要求声明指向翻译函数的变量时标识符必须与翻译函数的原始名称一致——i18n-calypso对应translatewordpress/react-i18n底层为wordpress/i18n对应__、_n、_nx、_x。规则定义见 i18n-translate-identifier.md源码实现见 i18n-translate-identifier.js。规则覆盖的两类调用场景从实现上看该规则只关注两个 calleeuseTranslate和useI18n。它们分别对应 Calypso 体系中两种主流的 React 国际化 hook来源库Hook允许的变量名说明automattic/i18n-calypso仓库中位于 packages/i18n-calypsouseTranslate()translate单个返回值直接赋值给变量wordpress/react-i18n/wordpress/i18nuseI18n()__、_n、_nx、_x对象返回值通过解构ObjectPattern取属性对应的常量定义在实现文件顶部const I18N_CALYPSO_TRANSLATE_FUNCTION translate; const WP_I18N_TRANSLATE_FUNCTIONS new Set( [ __, _n, _nx, _x ] );值得一提的是useTranslate的真实返回就是一个绑定了 i18n 实例的translate函数见 packages/i18n-calypso/src/use-translate.js所以变量名必须叫translate在语义上也是自洽的。哪些写法会被判定为警告warning以下模式来自原文档均会被规则报告场景一useTranslate返回值赋给非translate的变量名const __ useTranslate(); const t useTranslate();场景二从useI18n()解构翻译函数但重命名了标识符const { __: translate } useI18n(); const { _nx: _n } useTranslate();第二条值得注意文档示例中混用了useI18n与useTranslate来演示重命名即报错这一核心逻辑实际触发检查的是解构属性key是否属于允许集合以及key.name与value.name是否不一致。哪些写法是合规的non-warning场景一useTranslate返回值直接命名为translateconst translate useTranslate();场景二从useI18n()解构且不重命名const { __ } useI18n(); const { _n } useI18n(); const { _nx } useI18n(); const { _x } useI18n(); const { __, _n, _nx, _x } useI18n();边界情况与更多验证样本原文档之外规则配套的测试文件 lib/rules/test/i18n-translate-identifier.js 提供了更完整的判例可以帮助你精确理解检测边界合法validvar translate useTranslate(); const translate useTranslate(); let translate useTranslate(); useTranslate(); // 裸调用无变量声明不检测 const { isRTL } useI18n(); // 解构非翻译函数属性如 isRTL不检测 useI18n(); // 裸调用无变量声明不检测非法invalid及对应报错信息代码报错内容节选const __ useTranslate();Variable identifier should be named \translate ...const { __: translate } useI18n();... named \__ ...const { _nx: _n } useI18n();... named \_nx ...const { __, _n: translate } useI18n();... named \_n ...const { __: a, _n: b, _nx: c, _x: d } useI18n();依次报 4 条分别要求命名为__/_n/_nx/_x从中可以提炼出三条判定规则若声明的是useTranslate()的结果标识符必须精确等于translatevar/const/let均适用若从useI18n()解构出__/_n/_nx/_x之一不允许重命名key.name ! value.name即报错解构出来的非翻译函数属性如isRTL不受约束裸调用useTranslate()/useI18n()也不受约束。测试中还展示了错误消息模板Variable identifier should be named \{{translateFnName}} in order to be properly detected by the string extraction tools其中{{translateFnName}}会被替换为期望的原始函数名对应实现中的rule.ERROR_MESSAGE与data.translateFnName。深入实现规则是如何工作的规则的实现非常精简核心是一个监听CallExpression的处理器i18n-translate-identifier.js大致分为两个分支分支一useTranslate场景通过getCallee( node ).name useTranslate判定调用检查其父节点是否为VariableDeclarator且声明标识符存在若node.parent.id.name ! translate在声明标识符节点上报告错误。分支二useI18n场景判定 callee 为useI18n且父节点是VariableDeclarator进一步要求声明标识符类型为ObjectPattern即const { ... } useI18n()这种解构写法遍历properties仅当属性的key.name属于WP_I18N_TRANSLATE_FUNCTIONS且与value.name不一致时报告value就是解构后引入的本地变量名这也是const { __: a }重命名被识别的原因。callee 解析工具getCallee规则依赖的工具函数 lib/util/get-callee.js 会递归处理两类特殊情况SequenceExpression逗号表达式时取最后一个表达式MemberExpression时取属性部分支持obj.useTranslate()这类写法。此外规则还暴露了schema []表示它不接受任何配置选项属于零配置、即插即用的规则。如何在项目中启用该规则eslint-plugin-wpcalypso的推荐配置已经默认开启了这条规则recommended.js 中wpcalypso/i18n-translate-identifier: error所以最简单的做法是直接在.eslintrc中继承推荐配置{ extends: [ plugin:wpcalypso/recommended ] }React 项目也可以继承更完整的plugin:wpcalypso/react配置见 react.js它内部先扩展了 recommended再叠加 react/react-hooks 相关规则。如果只想单独启用这一条规则则先注册插件、再按需配置{ plugins: [ wpcalypso ], rules: { wpcalypso/i18n-translate-identifier: error } }安装方式与完整规则清单可参考 eslint-plugin-wpcalypso/README.mdyarn add --dev eslint eslint-plugin-wpcalypso与同族 i18n 规则的关系i18n-translate-identifier只是 Calypso 国际化 ESLint 规则家族中的一员。推荐配置里与翻译字符串相关的还有全部定义在 docs/rules 下i18n-ellipsis禁止在可翻译字符串中使用三个点号i18n-mismatched-placeholders确保单复数字符串的占位符数量一致i18n-named-placeholders禁止多个未命名占位符i18n-no-collapsible-whitespace禁止可翻译字符串中的可折叠空白i18n-no-placeholders-only禁止只包含占位符的字符串i18n-no-this-translate禁止this.translate()i18n-no-variables禁止用变量作为 translate 字符串i18n-unlocalized-url禁止未本地化的 URL。这一组规则从调用形式、标识符命名、字符串内容三个层面共同保障了提取管线能够稳定、完整地收获所有待翻译文案。i18n-translate-identifier负责的是其中最基础的一环——确保翻译函数的调用点以提取工具认识的名字出现。你在实际项目中可以先跑一遍eslint --fix或yarn lint让这条规则在 CI 阶段就拦截掉改名引入的漏翻译问题避免上线后出现未本地化的英文文案。赞分享前端CMS【免费下载链接】wp-calypsoThe JavaScript and API powered WordPress.com项目地址https://gitcode.com/gh_mirrors/wp/wp-calypso点击查看免费下载相关推荐wp-calypso i18n 规则 i18n-named-placeholders 深度解析为什么多个占位符必须命名ESLint 如何静态拦截wp calypso i18n 规则 i18n named placeholders 深度解析为什么多个占位符必须命名ESLint 如何静态拦截 本文以 e前端CMSwp-calypso 国际化规范ESLint 规则 i18n-no-variables 禁止变量作为 translate() 翻译字符串的完整解析wp calypso 国际化规范ESLint 规则 i18n no variables 禁止变量作为 translate 翻译字符串的完整解析 导读 在 Wo前端CMS音频解密终极指南如何免费解锁12种加密音乐格式音频解密终极指南如何免费解锁12种加密音乐格式 你是否曾经购买过数字音乐却发现只能在特定播放器上收听或者当你更换设备时那些精心收藏的音乐文件突然无法播放前端CMS上一篇如何快速掌握BepInEx面向游戏爱好者的终极插件框架指南下一篇GHelper完整指南华硕笔记本终极性能控制与硬件优化方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考