Skip to main content

i18n

Introduction​

maxGraph provides an internationalization (i18n) mechanism to support multiple languages in your application.

Some parts of the API return or display messages that can be translated using key/value pairs with optional parameter substitution.

The i18n mechanism is pluggable via the I18nProvider abstraction, so it allows you to use various i18n solutions, such as:

  • built-in solutions provided by maxGraph
  • custom implementations to use the i18n solution already used in your application.
warning

By default, maxGraph uses a no-op i18n implementation that provides no translations.

This keeps the library lightweight because not all applications need internationalization. Skipping built-in translations helps reduce bundle size and improve tree-shaking during the build process.

Built-in Provider​

maxGraph includes a built-in provider, TranslationsAsI18n, which uses the Translations class to load and manage resource files.

As mentioned in the previous paragraph, this mechanism is not enabled by default. So to use it in your application, configure it like this:

GlobalConfig.i18n = new TranslationsAsI18n();

By default, the following conventions apply:

  • Resource files use the .txt extension.
  • The default language is the browser's language, with a fallback to English.

You can override these defaults using the TranslationsConfig class. For example, the language support can be configured via TranslationsConfig.setLanguages.

maxGraph includes built-in translations for the following languages, covering Graph and Editor:

  • Chinese
  • English
  • French
  • German
  • Spanish

These resource files are located in the resources folder of the npm package:

  • resources/editor*.txt
  • resources/graph*.txt

The format of the resource files is as follows:

# Comment
key=value
# Another comment
key2=value2

Loading i18n Resources​

To load a resource, you need to:

  1. Ensure that the i18n files are available in your application so they can be fetched via a GET request. This usually involves copying the resource files from the maxGraph npm package into a dedicated folder within your application.
  2. Use either Translations.add or Translations.loadResources to load the required resources. When using Translations.loadResources, files are fetched from ${Client.basePath}/resources/.

Examples​

The Storybook demo showcases how to configure and use the i18n mechanism in different scenarios.

Resource files are loaded in the preview.ts file.

The following stories illustrate the translation of validation messages. Try connecting the same vertices twice to trigger a validation error displayed in a browser alert:

In the HelloPort story, select an edge to display a translated message in the tooltip of the bend point. (Note: The double-click action does not work, same behavior as in mxGraph.)

Custom Provider​

You can implement a custom i18n provider if your application already uses a different translation system.

To do this:

  1. Create a class that implements the I18nProvider interface — let's call it MyI18nProvider.
  2. Register it with:
GlobalConfig.i18n = new MyI18nProvider();

This gives you full control over how translations are handled inside maxGraph, making it easy to integrate with any existing i18n setup.