使用i18next搭配Handlebars时变量返回undefined的问题

算力阿峰

2026-8-18

解决i18next + Handlebars翻译返回undefined的问题

以下是针对你遇到的问题的排查和修复步骤：

1. 修复HandlebarsI18n初始化逻辑

你的代码中HandlebarsI18n.init()没有传入i18next实例和Handlebars实例，导致翻译helper无法关联到正确的i18n上下文。修改初始化代码：

import i18next from 'i18next';
import Handlebars from 'handlebars';
import HandlebarsI18n from "handlebars-i18n";
import resources from "./i18n/messages";

// 异步等待i18next初始化完成
i18next.init({
    resources,
    debug: true,
    fallbackLng: "en",
    lng : "en"
}).then(() => {
    // 传入i18next和Handlebars实例，完成helper注册
    HandlebarsI18n.init(i18next, Handlebars);
});

export default i18next;

2. 验证resources结构正确性

i18next的资源必须遵循{ 语言代码: { translation: { 键: 值 } } }的结构，确保你的messages.js格式正确：

// ./i18n/messages.js
export default {
  en: {
    translation: {
      Password: "Password",
      // 其他翻译键值对
    }
  },
  // 其他语言配置
};

3. 修正模板中变量的调用方式

如果使用动态变量，需要用括号包裹表达式，确保Handlebars正确解析：

{{__ (getNodeLabel .)}}

硬编码键名的写法{{__ "Password"}}是正确的，但需要确保资源中存在对应键。

4. 确保模板编译时机正确

在编译Handlebars模板前，必须等待i18next和HandlebarsI18n初始化完成。修改index.ts中的编译逻辑：

import i18n from './i18n';
import Handlebars from 'handlebars';
import templateSource from './template.hbs';

// 等待i18n初始化完成后再编译模板
i18n.then(() => {
  const template = Handlebars.compile(templateSource);
  const renderedHtml = template(yourData);
  // 执行渲染操作
});