5分钟上手ThingsBoard国际化：多语言配置与本地化实战指南

2026-02-05 04:16:32作者：柏廷章Berta

物联网平台的全球化部署需要完善的多语言支持，ThingsBoard作为开源IoT平台，提供了灵活的国际化方案。本文将从语言包结构、前端适配、动态切换三个维度，详解如何为设备管理界面、报表系统添加多语言支持，以及如何自定义本地化配置。

国际化架构概览

ThingsBoard的国际化系统基于Angular框架的i18n机制构建，核心实现包含：

语言包管理：JSON格式的翻译文件存储在ui-ngx/src/assets/locale/目录
翻译管道：通过i18nPrefix常量定义翻译键前缀，源码参见ui-ngx/src/app/shared/models/constants.ts
运行时切换：环境配置文件中声明默认语言与支持语言列表

// 环境配置示例 [ui-ngx/src/environments/environment.ts](https://gitcode.com/GitHub_Trending/th/thingsboard/blob/ce6f35872bf5a801edfd61e2fbdce5f7d62c243c/ui-ngx/src/environments/environment.ts?utm_source=gitcode_repo_files)
export const environment = {
  appTitle: 'ThingsBoard',
  production: false,
  supportedLangs: SUPPORTED_LANGS,  // 动态注入的语言列表
  defaultLang: 'en_US'              // 系统默认语言
};

语言包文件结构

翻译文件采用键值对结构，按功能模块组织。典型的翻译键命名规范为：{模块}.{组件}.{功能}.{描述}，例如：

{
  "dashboard": {
    "title": "仪表板",
    "add": "添加仪表板",
    "import": "导入仪表板"
  },
  "device": {
    "state": {
      "online": "在线",
      "offline": "离线"
    }
  }
}

系统预定义的翻译键可在ui-ngx/src/app/shared/models/limited-api.models.ts等文件中查看，包含API限制提示、设备状态描述等基础文本。

前端组件国际化实现

模板中使用翻译管道

在Angular模板中通过{{ '键名' | translate }}语法实现文本翻译：

<!-- 设备列表标题翻译示例 -->
<h2>{{ 'device.list.title' | translate }}</h2>

<!-- 带参数的翻译 -->
<p>{{ 'device.status' | translate:{ status: deviceState, time: lastUpdate } }}</p>

地图组件多语言适配

地图控件的图层名称等静态文本通过{i18n:}语法标记需要翻译的内容，源码参见ui-ngx/src/app/shared/models/widget/maps/map.models.ts：

// 地图图层翻译示例
{
  name: 'roadmap',
  label: '{i18n:widgets.maps.layer.roadmap}'  // 翻译键与图层类型关联
}

动态数据本地化

对于API返回的动态数据（如设备属性），使用localeCompare方法实现本地化排序：

// 本地化排序示例 [ui-ngx/src/app/shared/models/js-function.models.ts](https://gitcode.com/GitHub_Trending/th/thingsboard/blob/ce6f35872bf5a801edfd61e2fbdce5f7d62c243c/ui-ngx/src/app/shared/models/js-function.models.ts?utm_source=gitcode_repo_files#L115)
return a.propName.localeCompare(b.propName);

自定义语言扩展

添加新语言

在locale目录创建新语言文件：ui-ngx/src/assets/locale/zh_CN.json
配置构建脚本将新语言包纳入编译
修改环境配置添加语言支持

覆盖默认翻译

通过创建custom-translations.json文件实现翻译覆盖，优先级高于系统默认翻译：

{
  "dashboard.title": "我的仪表板",
  "device.state.online": "在线中"
}

国际化验证与测试

语言切换测试

使用浏览器开发工具修改localStorage中的language字段验证切换效果：

localStorage.setItem('language', 'fr_FR');
location.reload();  // 刷新后应用新语言

翻译完整性检查

运行专用的翻译检查工具，扫描未翻译的键值对：

cd ui-ngx
npm run check-translations  # 需在package.json中配置对应脚本

常见问题解决方案

日期时间本地化

使用Angular内置的DatePipe结合语言环境参数：

<!-- 日期本地化示例 -->
{{ eventTime | date:'medium':'':currentLang }}

数字与货币格式化

// 数字格式化服务示例
formatNumber(value: number, lang: string): string {
  return new Intl.NumberFormat(lang, {
    minimumFractionDigits: 2,
    maximumFractionDigits: 2
  }).format(value);
}

右键菜单动态翻译

上下文菜单等动态创建的组件，需在构造时注入翻译服务：

constructor(private translate: TranslateService) {
  this.menuItems = [
    { 
      label: this.translate.instant('action.edit'),
      action: () => this.onEdit()
    }
  ];
}