News from the project

I18N and Collapsed Pools

Published by Nico Rehwaldt on Monday, 21 March 2016.


We are proud to announce the latest release of bpmn-js. It adds the ability to translate the BPMN modeler into different languages (aka i18n) and allows you to model collapsed pools. On top of that it addresses a number of usability issues. Under the hood we performed some major improvements that should make it easier to work with bpmn-js as a library.

A collapsed pool is one of the elements we could import/render for a longer time. This release adds the ability to actually model it. To create a collapsed pool, replace an expanded one with it via the context pad:

You can change it back to an expanded pool, again via the element's context pad.

BPMN notice: We assume a collapsed pool to be a pool/participant without an attached process reference. It is not defined as part of the BPMN 2.0 spec, so your mileage using this BPMN concept may vary.

Translation Support (i18n)

We received a community contribution that adds internationalization to bpmn-js (and diagram-js underneath).

I18N is implemented via a function that receives a template as well as an object of replacements. As part of diagram-js we provide a dead simple default implementation.

In order to provide a custom translation you have to provide a custom translate function to the library:

function customTranslate(template, replacements) {

  if (template === 'Create {type}' && replacements.type === 'bpmn:StartEvent') {
    // we know German!
    return "Erzeuge ein Start-Ereignis";

  // fallback to default language otherwise


As part of your custom translate function you can use the translation technology of your choice.

To create a German BPMN modeler, provide the customTranslate function to bpmn-js during bootstrapping:

var translateGermanModule = {
  translate: [ 'value', customTranslate ]

var modeler = new BpmnModeler({
  addditionalModules: [ translateGermanModule ]

Have a look at our test suite for a translation example that knows Spanish and provides a fallback to the default language.

bpmn-js as a Library Improvements (TM)

This release brings significant improvements for using bpmn-js as a library.

Previously you had to import a BPMN diagram before accessing diagram services such as the CommandStack. Starting with this release, our BPMN modelers/viewers are instances of Diagram and share diagram services across imports. This also means that you can retrieve services before the initial import, too:

var modeler = new BpmnViewer({ ... });

// configure the modeler
var commandStack = modeler.get('commandStack');

$('#undo-button').click(function() {

// perform the diagram import

Hint: Try this with older bpmn-js versions ;-).

The bpmn-js instance (viewer/modeler) now exposes a set of import life-cycle events. These events allow you to hook into the diagram importing process, i.e., to easily react to import errors and warnings:

modeler.on('import.done', function(err, warnings) {

  if (err || warnings.length) {
    window.alert('IMPORT PROBLEMS!', err || JSON.stringify(warnings));


Note that we made the callback in Viewer#importXML optional, too.

What is next?

Based on the feedback we received in the last month we decided to dedicate the next bpmn-js milestone to huge diagrams. As part of the milestone we will work on features such as a global connect tool, copy and paste and other improvements.

Do you have valuable feedback on the topic? Tell us about it via our forums.

Make sure to follow us on Mastodon if you would like to keep track on what is happening in the bpmn-io sphere.

As always, get the latest bpmn-js release via npm or bower.

Are you passionate about JavaScript, modeling, and the web?
Join Camunda and build modeling tools people heart.