🌏 Internationalization (i18n)

TOAST UI Editor provides the ability to set the text set in UI in various languages. There are language files provided by default, you can import each language file and set the code ​​for the language you want to use when you create an instance.

Files Structure

Source File (For Contributors)

If you want to contribute language files in addition to the languages ​​supported by default, add them to the path below. See the Contributing section for a more detailed contributing process.

- tui.editor/apps/editor/src/
  - i18n/
    - en-us.ts
    - ko-kr.ts
    - ...

Build (For Maintainers)

- tui.editor/apps/editor/dist/
  - i18n/
    - ko-kr.js
    - ...

Files Distributed on npm

- node_modules/@toast-ui/editor/dist/
  - i18n/
    - ko-kr.js
    - ...

Files Distributed on CDN

- uicdn.toast.com/editor/latest/
  - i18n/
    - ko-kr.js
    - ko-kr.min.js
    - ...

Supported Languages

Below is a table of valid language codes for i18n files provided by the TOAST UI Editor. This language code is based on the IETF language tag. When you import a language file, the language code is registered and you can set the code as the option.

Note : The default language is English. The production language file(en-us.js) for English is not provided and you don’t need to import this file.

Importing Language Files

You must register the language by importing the language file you want to use. The ${fileName} is corresponding to the ‘i18n File’ column in Supported Languages (Can be used without an extension).

ES Modules

import '@toast-ui/editor/dist/i18n/${fileName}';

CommonJS

require('@toast-ui/editor/dist/i18n/${fileName}');

Usage CDN

You must register the language by including the language file you want to use. The ${fileName} is corresponding to the ‘i18n File’ column in Supported Languages. It also provides a minified version.

<script src="https://uicdn.toast.com/editor/latest/i18n/${fileName}"></script>

How to Use

Note : The following examples are based on npm usage.

Use Case 1 : Basic Usage

If you want to set a specific language, you can use the language option to create an instance. The value of this option corresponds to the ‘Registered Code’ column in Supported Languages. The default value is en and en-US.

import Editor from '@toast-ui/editor';
// Step 1 : Import language file
import '@toast-ui/editor/dist/i18n/ko-kr';
// Step 2 : Set language each editor
const foo = new Editor({
  // Use default language in English
  // ...
});
const bar = new Editor({
  // Use other language
  // ...
  language: 'ko-KR',
});

Use Case 2 : Some Value Overrides

Use the setLanguage static method to override the value for a specific language code. See here for default values.

import Editor from '@toast-ui/editor';
// Step 1 : Import language file
import '@toast-ui/editor/dist/i18n/ko-kr';
// Step 2 : Override values of language
Editor.setLanguage('en-US', {
  'Add row': '[Add Row]', // Default value is 'Add row'
});
Editor.setLanguage('ko-KR', {
  'Add row': '[로우 추가]', // Default value is '행 추가'
});
// Step 3 : Set language each editor
const foo = new Editor({
  // Use default language in English
  // ...
});
const bar = new Editor({
  // Use other language
  // ...
  language: 'ko-KR',
});

Use Case 3 : New Language Registration

If the language you want to use is not provided by default, you can register it with the setLanguage static method.

import Editor from '@toast-ui/editor';
// Step 1 : Register new language
Editor.setLanguage('en-GB', {
  Markdown: '...',
  WYSIWYG: '...',
  // ...
});
// Step 2 : Set language with new registration code
const bar = new Editor({
  // ...
  language: 'en-GB',
});

Contributing

If you want to contribute to providing a different language file, follow this process:

Step 1

Fork the repository and add the language file to the path below. The name of the language file follows the ${languageCode}-${countryCode}.js convention. languageCode and countryCode must be written in lowercase. (e.g. en-gb.ts)

Reference : Nominatim/Country Codes

- tui.editor/apps/editor/src/
  - i18n/
    - en-us.ts
    - ko-kr.ts
    - ...

Step 2

Refer to this file and write each parameter value used when calling the setLanguage method.

The first parameter is a code value that maps to the language file to register. Code values ​​follow the ${languageCode}-${countryCode} convention. languageCode must be in lowercase and countryCode in uppercase.

// th-th.js
// ...
Editor.setLanguage('th-TH', {
  Markdown: '...',
  WYSIWYG: '...',
  // ...
});

If the following conditions are satisfied, the language code except for the country code can be added.

IETF Language Tag’s Reference : Optional script and region subtags are preferred to be omitted when they add no distinguishing information to a language tag. For example, es is preferred over es-Latn, as Spanish is fully expected to be written in the Latin script; ja is preferred over ja-JP, as Japanese as used in Japan does not differ markedly from Japanese as used elsewhere.

Not all linguistic regions can be represented with a valid region subtag: the subnational regional dialects of a primary language are registered as variant subtags. For example, the valencia variant subtag for the Valencian dialect of Catalan is registered in the Language Subtag Registry with the prefix ca. As this dialect is spoken almost exclusively in Spain, the region subtag ES can normally be omitted.

// th-th.js
// ...
Editor.setLanguage(['th', 'th-TH'], {
  Markdown: '...',
  WYSIWYG: '...',
  // ...
});

Example

You can see the example here.