5个步骤掌握bpmn-js国际化：从基础配置到动态切换

解析国际化需求痛点

在全球化协作日益频繁的今天，BPMN建模工具的国际化（i18n，Internationalization的缩写）支持已成为企业级应用的必备能力。想象这样三个场景：跨国团队使用同一套流程建模工具时，德国工程师看到的界面按钮是"Speichern"，而中国同事却需要"保存"；合规审计要求流程元素必须使用本地化术语；客户希望根据用户角色动态切换界面语言。这些真实需求背后，隐藏着三个核心痛点：多语言界面适配、专业术语定制和动态语言切换。

bpmn-js作为一款广泛应用的BPMN 2.0建模工具，其国际化方案正是为解决这些痛点而生。通过灵活的翻译机制和可扩展的配置接口，开发者可以轻松实现从基础语言切换到深度定制化翻译的全流程需求。

技术原理解析

翻译加载机制解密

bpmn-js的国际化核心采用"优先级覆盖"机制，就像餐厅服务流程：当顾客（用户）有特殊要求（自定义翻译）时，优先提供定制菜单（自定义翻译文件）；没有特殊要求时，则使用餐厅标准菜单（默认翻译）。这一机制通过三级加载优先级实现：

1. 内联配置翻译：通过初始化参数直接注入的翻译项，优先级最高
2. 自定义翻译文件：用户提供的完整翻译文件，优先级次之
3. 默认翻译文件：项目内置的标准翻译，优先级最低

核心实现位于lib/util/目录下的翻译工具函数，通过translate方法完成文本替换。当系统需要显示某段文本时，会按上述优先级顺序查找对应的翻译内容，确保最终展示最符合用户需求的语言版本。

翻译文件结构解析

默认翻译文件docs/translations.json采用数组结构存储所有可翻译文本，每个元素对应界面中的一个固定字符串。以下是不同语言包的结构对比：

语言包类型	存储位置	结构特点	适用场景
默认翻译	docs/translations.json	基础数组结构，128个核心翻译项	通用场景，快速上手
自定义翻译	任意位置	与默认文件索引严格对应	术语定制，品牌化需求
扩展翻译	自定义文件	在默认结构基础上追加新项	功能扩展，新增模块

这种结构设计确保了翻译系统的轻量高效，同时为扩展提供了明确路径。每个翻译项通过数组索引而非键名关联，这要求自定义翻译文件必须保持与默认文件的索引顺序一致。

阶梯式实践指南

基础配置：快速切换语言

✅ 步骤1：准备环境 首先确保已克隆项目仓库：

git clone https://gitcode.com/gh_mirrors/bp/bpmn-js
cd bpmn-js
npm install

✅ 步骤2：初始化配置 在创建Modeler实例时指定语言参数：

// 基础版：指定内置语言
const modeler = new BpmnJS({
  container: '#canvas',
  locale: 'zh-CN'  // 支持的语言代码：en, de, fr, zh-CN等
});

⚠️ 注意事项：若未找到指定语言的完整翻译，系统会自动回退到英文默认值。

高级定制：构建自定义语言包

✅ 步骤1：创建翻译文件 复制默认翻译文件作为模板：

cp docs/translations.json custom-translations.json

✅ 步骤2：编辑翻译内容 修改或添加翻译项，保持数组结构和索引顺序：

[
  "激活创建/删除空间工具",  // 覆盖默认翻译
  "激活全局连接工具",
  "即席子流程",  // 行业术语定制
  // ... 保持其他项索引不变
  "流程元素必须是池/参与者的子元素"
]

✅ 步骤3：加载自定义翻译

// 进阶版：使用自定义翻译文件
import customTranslations from './custom-translations.json';

const modeler = new BpmnJS({
  container: '#canvas',
  translations: customTranslations  // 注入自定义翻译
});

场景化应用：动态语言切换

企业级应用往往需要根据用户操作实时切换界面语言，以下是实现方案：

// 企业版：动态切换语言
async function switchLanguage(locale, customTranslations) {
  // 1. 获取当前翻译服务实例
  const translate = modeler.get('translate');
  
  // 2. 加载新语言翻译文件
  const newTranslations = customTranslations || await loadDefaultTranslations(locale);
  
  // 3. 更新翻译存储
  translate.setTranslations(newTranslations);
  
  // 4. 触发界面重渲染
  modeler.get('eventBus').fire('i18n.language.changed', { locale });
}

// 使用示例
switchLanguage('fr', frenchTranslations);

图：bpmn-js界面语言动态切换效果展示

行业应用案例

案例1：跨国制造企业流程标准化

某汽车制造商通过自定义翻译文件，将BPMN元素统一为行业术语（如将"Task"译为"工序"，"Gateway"译为"决策点"），确保全球工厂使用统一的流程语言，减少沟通成本30%。

案例2：金融合规系统本地化

某银行在实施合规流程管理系统时，通过动态语言切换功能，使中文用户看到"风险评估"，英文用户看到"Risk Assessment"，同时保持流程结构完全一致，满足多语言审计需求。

排障与优化

常见问题解决

翻译不生效

1. 索引不一致：检查自定义翻译文件与默认文件的数组长度是否相同
2. 加载顺序问题：确保自定义翻译在初始化时正确注入
3. 缓存影响：动态切换语言后需强制刷新界面元素

特殊字符处理

翻译文本中的特殊字符需按JSON规范转义：

"数据对象必须放置在\"池/参与者\"内。"

性能优化

翻译文件加载策略

1. 按需加载：仅加载当前语言所需的翻译文件，减少初始加载体积
2. 缓存机制：实现翻译内容本地存储，避免重复请求

// 简单缓存实现示例
function loadTranslations(locale) {
  const cacheKey = `i18n_${locale}`;
  const cached = localStorage.getItem(cacheKey);
  
  if (cached) {
    return Promise.resolve(JSON.parse(cached));
  }
  
  return fetch(`/translations/${locale}.json`)
    .then(response => response.json())
    .then(data => {
      localStorage.setItem(cacheKey, JSON.stringify(data));
      return data;
    });
}

3. 预加载关键翻译：优先加载界面核心元素的翻译，非关键内容延迟加载

总结

通过本文介绍的5个步骤，你已掌握bpmn-js国际化的完整实现路径：从基础语言切换到自定义翻译文件，再到动态语言切换。核心要点包括理解翻译加载机制、保持翻译文件索引一致、实现高效的语言切换逻辑。合理应用这些技术，能让你的BPMN建模工具更好地服务于全球化团队，提升协作效率和用户体验。

完整的国际化实现细节可参考项目源码中lib/util/目录下的相关模块，官方文档docs/project/SETUP.md也提供了环境配置的基础指南。