进阶 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", ... } 这样,如果用户使用的语言你的插件不支持,加载插件的语言资源时会看到西班牙语翻译,因为它是指定的回退语言。

评论 (0)