# Internationalization

The I18n module allows you to translate and update strings in the editor UI.

WARNING

This guide applies to GrapesJS v0.15.9 or higher.

We welcome help with translating strings into other languages. Your contributions are much appreciated!

Configuration
Update strings
- Generated strings
Adding new language
Plugin development

# Configuration

By default, the editor includes only English. If you need other languages, import them manually. Note: The language code is defined in the ISO 639-1 (opens new window) standard.

import grapesjs from 'grapesjs';
import it from 'grapesjs/locale/it';
import tr from 'grapesjs/locale/tr';

const editor = grapesjs.init({
  ...
  i18n: {
    // locale: 'en', // default locale
    // detectLocale: true, // by default, the editor will detect the language
    // localeFallback: 'en', // default fallback
    messages: { it, tr },
  }
});

The editor will now be translated into Italian in browsers whose default language is Italian (the detectLocale option is enabled by default).

# Update strings

If you need to change default language strings, you can update them using the I18n API. To find the correct path for a string, check the en locale file (opens new window) and follow its path inside the locale object.

Let's say we want to update the default empty state message in the Style Manager when no elements are selected.

You can find it in the en locale file at the following path:

{
    ...
    styleManager: {
        empty: 'Select an element before using Style Manager',
        ...
    },
    ...
}

To update it, do this:

editor.I18n.addMessages({
  en: {
    // indicate the locale to update
    styleManager: {
      empty: 'New empty state message',
    },
  },
});

Although the UI displays the updated message correctly, we strongly recommend wrapping all API calls in a plugin.

const myPlugin = editor => {
    editor.I18n.addMessages({ ... });
    // ...
}

grapesjs.init({
  // ...
  plugins: [myPlugin],
});

# Generated strings

Not all strings are listed in the en locale file, as some can be generated from ids, names, etc. If you look back at the styleManager path in the en file, you'll notice the empty properties object:

...
styleManager: {
    ...
    properties: {
        // float: 'Float',
    },
    ...
},
...

This object is used to translate property names in the Style Manager. For instance, if you need to change the auto-generated names for the margin properties

you'd do this:

editor.I18n.addMessages({
  en: {
    styleManager: {
      properties: {
        // The key is the property name (or id)
        'margin-top': 'Top',
        'margin-right': 'Right',
        'margin-left': 'Left',
        'margin-bottom': 'Bottom',
      },
    },
  },
});

# Adding new language

To support GrapesJS by adding a new language to our repository, follow the steps below:

First, check that the language file doesn't already exist in src/i18n/locale (opens new window).
Open a new issue (opens new window) to avoid overlap with other contributors. Also check that no one has already opened an issue for the same language.
Start a new branch from dev.
Copy the en locale file (opens new window) into the same folder and rename it using the ISO 639-1 (opens new window) code for your chosen language.
Start translating strings.
By following the comments, you'll notice that some keys are not listed (e.g., styleManager.properties). You can check other locale files for reference.
Once you're done, create a pull request on GitHub from your branch to dev. Reference your issue so it closes automatically when the PR is merged (your PR message should contain Closes #1234, where 1234 is the issue ID).

# Plugin development

WARNING

This section is intended only for plugin developers. You can skip it if you use grapesjs-cli (opens new window) to initialize your plugin project.

If you're developing a plugin for GrapesJS and need to support localized strings or change the default strings, we recommend the following structure.

plugin-dir
- package.json
- README.md
- ...
- src
    - index.js
    - locale // create the locale folder in your src
        - en.js // All default strings should be placed here

Place strings specific to your plugin under a key matching the plugin name:

// src/locale/en.js
export default {
  'grapesjs-plugin-name': {
    yourKey: 'Your value',
  },
};

In your index.js, use the en.js file and add an i18n option to allow other locale files to be imported:

// src/index.js
import en from 'locale/en';

export default (editor, opts = {}) => {
  const options = {
    i18n: {},
    // ...
    ...opts,
  };

  // ...

  editor.I18n.addMessages({
    en,
    ...options.i18n,
  });
};

The next step is to compile your locale files into the <rootDir>/locale directory to make them easily accessible to your users. This folder can be ignored in your Git repository but should be published to the npm registry.

WARNING

You can skip these steps and initialize your project with grapesjs-cli (opens new window). This creates all the necessary folders/files/commands for you. During the init command, this option is set to true by default, and we recommend keeping it enabled even if your project does not require i18n.

Your plugin users will then be able to import other locale files (if they exist) like this:

import grapesjs from 'grapesjs';

// Import from your plugin
import yourPlugin from 'grapesjs-your-plugin';
import ch from 'grapesjs-your-plugin/locale/ch';
import fr from 'grapesjs-your-plugin/locale/fr';

const editor = grapesjs.init({
  ...
  plugins: [ yourPlugin ],
  pluginsOpts: {
      [yourPlugin]: {
          i18n: { ch, fr }
      }
  }
});

← Commands Selectors →