Internationalization (i18n)

UnderFlow can show its UI text in various languages. Import the texts for each language you want to use, register them under their language codes, then set the language code when you create an instance.

Locale Files

Each locale is a separate entry point, @liquid-js/underflow/i18n/<locale>, that exports the locale's texts and does nothing else, so importing it has no side effects. The source files are in src/editor/i18n/; see Contributing if you want to add a language.

Supported Languages

Below is a table of the locale files included in UnderFlow, the name of the texts each one exports and the language codes to register them under. The codes are IETF language tags.

Note: The default language is English. It's always available, so you don't need to import i18n/en-us.

Language Name	Import Path	Export	Language Code
Arabic	`ar`	`ar`	`ar`
Chinese (S)	`zh-cn`	`zhCN`	`zh-CN`
Chinese (T)	`zh-tw`	`zhTW`	`zh-TW`
Croatian (Croatia)	`hr-hr`	`hrHR`	`hr` \| `hr-HR`
Czech (Czech Republic)	`cs-cz`	`csCZ`	`cs` \| `cs-CZ`
Dutch (Netherlands)	`nl-nl`	`nlNL`	`nl` \| `nl-NL`
English (United States)	`en-us`	`enUS`	`en` \| `en-US`
Finnish (Finland)	`fi-fi`	`fiFI`	`fi` \| `fi-FI`
French (France)	`fr-fr`	`frFR`	`fr` \| `fr-FR`
Galician (Spain)	`gl-es`	`glES`	`gl` \| `gl-ES`
German (Germany)	`de-de`	`deDE`	`de` \| `de-DE`
Indonesian (Indonesia)	`id-id`	`idID`	`id` \| `id-ID`
Italian (Italy)	`it-it`	`itIT`	`it` \| `it-IT`
Japanese (Japan)	`ja-jp`	`jaJP`	`ja` \| `ja-JP`
Korean (Korea)	`ko-kr`	`koKR`	`ko` \| `ko-KR`
Norwegian Bokmål (Norway)	`nb-no`	`nbNO`	`nb` \| `nb-NO`
Norwegian Nynorsk (Norway)	`nn-no`	`nnNO`	`nn` \| `nn-NO`
Persian (Iran)	`fa-ir`	`faIR`	`fa` \| `fa-IR`
Polish (Poland)	`pl-pl`	`plPL`	`pl` \| `pl-PL`
Portuguese (Brazil)	`pt-br`	`ptBR`	`pt` \| `pt-BR`
Russian (Russia)	`ru-ru`	`ruRU`	`ru` \| `ru-RU`
Spanish (Castilian, Spain)	`es-es`	`esES`	`es` \| `es-ES`
Swedish (Sweden)	`sv-se`	`svSE`	`sv` \| `sv-SE`
Turkish (Turkey)	`tr-tr`	`trTR`	`tr` \| `tr-TR`
Ukrainian (Ukraine)	`uk-ua`	`ukUA`	`uk` \| `uk-UA`
Vietnamese (Vietnam)	`vi-vn`	`viVN`	`vi` \| `vi-VN`

Registering Languages

Import a locale's texts and register them with the setLanguage static method, under the codes from the 'Language Code' column in Supported Languages:

import { Editor } from '@liquid-js/underflow'
import { deDE } from '@liquid-js/underflow/i18n/de-de'

Editor.setLanguage(['de', 'de-DE'], deDE)

As the locales are plain data, they can also be loaded only when they're needed:

const { deDE } = await import('@liquid-js/underflow/i18n/de-de')

Editor.setLanguage(['de', 'de-DE'], deDE)

How to Use

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 is one of the codes the language is registered under. The default value is en-US.

import { Editor } from '@liquid-js/underflow'
import { deDE } from '@liquid-js/underflow/i18n/de-de'

// Step 1 : Register the language
Editor.setLanguage(['de', 'de-DE'], deDE)

// Step 2 : Set language each editor
const englishEditor = new Editor({
    // Use default language in English
    // ...
})

const germanEditor = new Editor({
    // Use other language
    // ...
    language: 'de-DE'
})

Use Case 2 : Some Value Overrides

setLanguage merges the texts into those already registered for a language code, so it can also override single values. See texts/en-us.ts for the default values.

import { Editor } from '@liquid-js/underflow'
import { deDE } from '@liquid-js/underflow/i18n/de-de'

// Step 1 : Register the language
Editor.setLanguage(['de', 'de-DE'], deDE)

// Step 2 : Override values of the languages
Editor.setLanguage('en-US', {
    'Add row to up': 'Insert row above' // Default value is 'Add row above'
})

Editor.setLanguage('de-DE', {
    'Add row to up': 'Zeile oberhalb einfügen' // Default value is 'Zeile nach oben hinzufügen'
})

// Step 3 : Set language each editor
const englishEditor = new Editor({
    // Use default language in English
    // ...
})

const germanEditor = new Editor({
    // Use other language
    // ...
    language: 'de-DE'
})

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 '@liquid-js/underflow'

// Step 1 : Register new language
Editor.setLanguage('en-GB', {
    Markdown: '...',
    WYSIWYG: '...'
    // ...
})

// Step 2 : Set language with new registration code
const britishEditor = 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}.ts convention. languageCode and countryCode must be written in lowercase. (e.g. en-gb.ts)

Reference : Nominatim/Country Codes

- src/editor/
  - i18n/
    - en-us.ts
    - de-de.ts
    - ...

Step 2

Refer to texts/en-us.ts and translate every text. The file exports only the texts, named after the file in camel case (th-th.ts exports thTH):

// th-th.ts
export const thTH: Record<string, string> = {
    Markdown: '...',
    WYSIWYG: '...'
    // ...
}

Step 3

Add the language to Supported Languages with the codes to register it under. Codes follow the ${languageCode}-${countryCode} convention: languageCode in lowercase and countryCode in uppercase, e.g. th-TH.

If the following conditions are satisfied, the language code without the country code can be added as well, e.g. th.

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.