进阶 docs.nodebb.org 2026-10-13 15:07:09 · 31 阅读
第57章 NodeBB 插件与主题国际化 (i18n) 开发指南
Internationalising your Plugin/Theme
你可以根据喜好自由选择编写插件或主题所使用的语言,但若需支持多语言,则可利用 NodeBB 内置的语言引擎。
本文以插件为例进行说明。由于主题本质上也是插件,因此两者的实现方式完全相同。
步骤 1:定义翻译目录结构
首先,让我们来定义语言键和对应的翻译。在插件中创建一个新目录来存放翻译文件。注意,该目录内部的文件结构必须与 NodeBB 自身保持一致:每个子目录以语言键命名(例如 en-GB),并包含承载实际翻译内容的 .json 文件。
$ cd /path/to/my/plugin
$ mkdir -p languages/en-GB
$ mkdir -p languages/es
在上面的命令中,我创建了 languages 文件夹,包含两种语言:英语(en-GB)和西班牙语(es)。
步骤 2:添加翻译内容
在步骤 1 创建的子目录中,我将创建扩展名为 .json 的文本文件。这些文件将存储插件的翻译文本。
languages/en-GB/myplugin.json 文件内容:
{
"greeting": "Hello there! How are you?"
}
languages/es/myplugin.json 文件内容:
{
"greeting": "Hola! Como estás?"
}
文件名可以随意命名,但最好使用可辨识的名称(例如与插件相关的名称)。你也可以将文件命名为 NodeBB 中已存在的语言文件同名。NodeBB 会自动将这两组本地化集合合并为一个集合。例如,NodeBB 包含一个 user.json 文件。你也可以将你的文件命名为 user.json,这样在插件或主题中就可以同时调用这两个文件中的语言字符串。
注意
请务必将 myplugin 更改为与你的插件相关的名称!
步骤 3:告知 NodeBB 加载语言文件
NodeBB 不会自动知道你有需要加载的翻译,因此我们需要在 plugin.json 文件中添加一行配置,告知 NodeBB 加载语言文件及其存放位置。
打开 plugin.json 并添加一个新属性 languages:
{
...
"languages": "languages",
...
}
此属性的值是语言文件所在路径,相对于插件根目录。在本例中,我将语言文件放在插件根目录下的 languages 文件夹中,因此只需填入 languages。如果语言文件位于名为 public 的子文件夹中,则此处正确的值应为 public/languages。
步骤 4:在插件中使用翻译
你可以在插件中以多种方式使用翻译:
服务端
在服务端代码中,可以按以下方式调用翻译引擎:
var translator = require.main.require('./src/translator');
translator.translate('[[myplugin:greeting]]', function(translated) {
console.log('Translated string:', translated);
});
注意
服务端调用将翻译为 ACP 设置中服务器默认的语言:http:///admin/general/languages
客户端
在浏览器中,可以按以下方式调用翻译引擎:
require(['translator'], function(translator) {
translator.translate('[[myplugin:greeting]]', function(translated) {
console.log('Translated string:', translated);
});
});
注意
客户端调用将翻译为用户设置中的语言:http:///user//settings
模板
在模板中,你无需执行特殊操作即可调用翻译引擎,它会自动运行,并解析符合以下语法的任何语言字符串:[[resource:key]]。因此,对于我们的插件:
[[myplugin:greeting]]
在翻译中传入变量 翻译字符串可以包含位置占位符 %1、%2 等。在语言字符串引用中以逗号分隔的参数提供对应的值: { "welcome": "Welcome back, %1! You have %2 new messages." }[[myplugin:welcome, {username}, {messageCount}]]
只要允许使用语言字符串的地方,这种逗号语法都适用,包括通知的 bodyShort 这类服务端字符串。 当你需要用动态值构建语言字符串时,不要手动拼接——如果某个参数本身包含逗号或 %,会破坏整个翻译。应使用 translator.compile,它会自动转义每个参数中的这些字符: const translator = require.main.require('./src/translator'); // translator.compile(key, ...params) bodyShort: translator.compile('myplugin:welcome', username, count) 在 async/await 中使用 translator translator.translate 采用回调风格。如果想在 async 函数中使用,可以用 Promise 包一层: const translator = require.main.require('./src/translator'); const greeting = await new Promise((resolve) => { translator.translate('[[myplugin:greeting]]', resolve); }); (可选)第 5 步:指定默认语言 NodeBB 本身支持约 40 种语言,你不可能把插件翻译成所有语言!要指定某种默认语言,只需在 plugin.json 中添加 defaultLang 属性: { ... "languages": "languages", "defaultLang": "es", ... } 这样,如果用户使用的语言你的插件不支持,加载插件的语言资源时会看到西班牙语翻译,因为它是指定的回退语言。