WordPress Gutenberg 国际化(i18n)开发完全指南
项目地址: https://gitcode.com/GitHub_Trending/gu/gutenberg 什么是国际化(i18n)？
国际化(Internationalization，简称i18n)是指为软件提供多语言支持的技术过程。在WordPress生态中，i18n允许插件和主题开发者将界面文本设计为可翻译的格式，从而让全球用户能够使用自己的母语与产品交互。
i18n中的"18"代表首字母"i"和末尾字母"n"之间的字符数，这种缩写方式在技术社区中已成为标准。WordPress通过成熟的翻译系统，让社区成员能够为各种插件和主题贡献翻译，而开发者只需专注于代码层面的国际化支持。
JavaScript国际化实现
随着WordPress 5.0引入Gutenberg编辑器，WordPress为JavaScript代码提供了与PHP类似的国际化方案。核心是wp-i18n这个JavaScript包，它提供了一系列翻译函数。
基础配置
首先需要在注册脚本时声明依赖关系：
function myguten_block_init() {
wp_register_script(
'myguten-script',
plugins_url( 'block.js', __FILE__ ),
array( 'wp-blocks', 'react', 'wp-i18n', 'wp-block-editor' )
);
// ...其他注册代码
}
常用翻译函数
在JavaScript代码中，主要使用以下函数：
-
简单翻译：
__( '文本内容', '文本域' )title: __( '简单区块', 'myguten' ) -
复数形式：
_n( '单数形式', '复数形式', 数量, '文本域' )_n( '%s 条评论', '%s 条评论', commentCount, 'myguten' ) -
带上下文的翻译：
_x( '文本内容', '上下文说明', '文本域' )_x( '默认', '区块样式', 'myguten' )
关键注意事项
- 所有面向用户的字符串都应包裹在i18n函数中
- 文本域(text domain)必须与插件/主题的标识完全一致
- 翻译函数应直接用于字符串常量，不能用于动态拼接的字符串
翻译文件处理流程
1. 生成POT模板文件
使用命令行工具提取所有可翻译字符串：
mkdir languages
wp i18n make-pot ./ languages/myguten.pot
生成的POT文件包含所有待翻译的原始字符串。
2. 创建PO翻译文件
以目标语言代码(如中文zh_CN)创建PO文件：
cp myguten.pot myguten-zh_CN.po
编辑PO文件，填充msgstr翻译内容：
msgid "Hello World"
msgstr "你好世界"
3. 转换为JSON格式
WordPress JavaScript翻译使用JED 1.x JSON格式：
wp i18n make-json myguten-zh_CN.po --no-purge
这将生成类似myguten-zh_CN-[hash].json的文件。
加载翻译文件
在PHP中指定翻译文件位置：
function myguten_set_script_translations() {
wp_set_script_translations(
'myguten-script',
'myguten',
plugin_dir_path( __FILE__ ) . 'languages'
);
}
add_action( 'init', 'myguten_set_script_translations' );
WordPress会自动查找符合以下格式的文件：
${domain}-${locale}-${handle}.json- 或
${domain}-${locale}-${md5}.json
测试与调试技巧
- 设置站点语言：在"设置 > 常规"中修改站点语言
- 开发工具检查：在浏览器控制台查看
wp.i18n状态 - 缓存问题：翻译文件更改后可能需要清除缓存
- 占位符检查：确保动态内容(如%s)在翻译中保留
高级主题
翻译过滤器
WordPress提供了对翻译结果的过滤机制，允许开发者动态修改翻译输出。例如：
add_filter( 'i18n.hello_world_translation', function( translation ) {
return '自定义: ' + translation;
} );
性能优化
- 合并翻译文件减少HTTP请求
- 仅在需要时加载翻译
- 避免在频繁执行的代码中使用复杂翻译函数
最佳实践
- 一致性：保持文本域在整个项目中一致
- 完整覆盖：确保UI中所有可见文本都被国际化
- 上下文明确：为模糊字符串提供足够上下文
- 测试各种语言：特别是RTL(从右到左)语言布局
- 社区协作：将POT文件提交到翻译平台让社区参与
通过遵循这些指南，开发者可以创建真正全球化的Gutenberg区块和插件，为WordPress的国际化生态系统做出贡献。
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
