Custom Strings

Appmixer SDK allows you to change all the strings of all the UI widgets it provides (Designer, FlowManager, Insights, ...). This is especially useful to localize the entire Appmixer UI.

Setting Custom Strings

A strings object is represented as a JSON object that you set on your Appmixer SDK instance using the set('strings', myStrings) method:

var appmixer = new Appmixer({ baseUrl: BASE_URL });
appmixer.set('strings', STRINGS);

You can set the strings object anywhere in your application but usually you'll do that right after initializing your appmixer instance. Note that you can even set the strings multiple times with different configuration in which case the Appmixer SDK will automatically re-render all the UI widgets using the new strings configuration.

If you don't set strings, the default strings will be applied.

Structure of the Strings Object

The strings object is a JSON object (with one exception, see below) that contains references to various UI elements within the Appmixer UI. The final values of the JSON objects are the actual strings used in the UI.

Example of setting the strings object:

appmixer.set('strings', {
  flowManager: {
    header: {
      btnCreate: 'Create new Flow',
      search: 'Search flows'
    }
  }
});

Complete Strings Object

For reference, we prepared a complete strings object for you to download and inspect to see all the possibilities for strings customization/localization.

35KB

appmixer-strings-en.json

Time Localization

For localization of time related strings, a special time root scope of the strings object can be modified:

appmixer.set('strings', {
  time: {
    months: [...],
    monthsShort: [...],
    weekDaysShort: [...],
    ordinal(number){ ... },
    relativeTime: {...}
  }
});

Please download the default strings object above to see all the possiblities for time localization. Notice in the code above that there is one speciality to the time localization which (if used) makes the strings object non-JSON compliant. That's the ordinal(number) function. Given a number, this function returns a string representing of the number in ordinal form (i.e. 1 becomes "1st", 2 becomes "2nd", ...). Since this is hard to describe declaratively in JSON, the strings object may contain the oridnal(number) function for you to be able to localize ordinal numbers. The default implementation looks like this:

ordinal(number) {
   const b = number % 10;
   const output = (~~(number % 100 / 10) === 1) ? 'th'
       : (b === 1) ? 'st'
           : (b === 2) ? 'nd'
               : (b === 3) ? 'rd' : 'th';
   return number + output;
}

Pluralization and Strings with Variables

Some text can contain both singular and plural versions based on whether the number variable used inside the text equals 1 or not. For example, the pagination widget in the Flows Manager:

The "of 8 flows" string used above can vary based on whether the total number of flows is more than one or if it equals one. The two versions can be expressed using the | character in the strings object like so:

appmixer.set('strings', {
  flowManager: {
    header: {
      pagination: 'of {{total}} flow|of {{total}} flows'
    }
  }
});

Also notice the use of variables ({{total}} in the example above). Variables are always enclosed by two curly brackets and are replaced by the SDK with the actual numbers when used. See the Appmixer default strings object for all occurrences of variables.

Slots

Sometimes words inside longer text have some functionality bound to them, typically a clickable link. For example, the Flow Manager displays the following text when there are no flows created yet:

The word "here", when clicked, opens up the Designer for the user to create a new flow. So how to localize the text and keep the functionality? Enter slots. Slots allow us to keep the functionality (and sometimes styling) bound to the words inside our localized strings. The strings object for this scenario looks like this:

appmixer.set('strings', {
  flowManager: {
    messageNoFlows: {
      text: 'Click (@createFlow)here(/@createFlow) to create a new flow'
    }
  }
});

The tokens (@createFlow) and (/@createFlow) are quite similar to html tags, meaning that what is between them will be bound to the event described by the token names (i.e. createFlow event).