Universal Unicode to Latin transliteration + slugify module. Works on all platforms and with all major languages.

Demo

Try it out

Compatibility / Browser support

IE 9+ and all modern browsers, Node.js, Web Worker, React Native and CLI

Installation

Node.js / React Native

1npm install transliteration --save

If you are using Typescript, please do not install @types/transliteration. Since in verson 2.x, type definition files are built-in within this project.

1import { transliterate as tr, slugify } from 'transliteration';
2
3tr('你好, world!');
4// Ni Hao , world!
5slugify('你好, world!');
6// ni-hao-world

Browser (CDN):

1<!-- UMD build -->
2<script
3  async
4  defer
5  src="https://cdn.jsdelivr.net/npm/transliteration@2.1.8/dist/browser/bundle.umd.min.js"
6></script>
7<script>
8  console.log(transliterate('你好'));
9</script>

1<!-- ESM build -->
2<script type="module">
3  import { transliterate } from 'https://cdn.jsdelivr.net/npm/transliteration@2.1.8/dist/browser/bundle.esm.min.js';
4  console.log(transliterate('你好'));
5</script>

transliteration can be loaded as an AMD / CommonJS module, or as global variables (UMD).

When you use it in the browser, by default it creates three global variables under window object:

1transliterate('你好, World');
2// window.transliterate
3slugify('Hello, 世界');
4// window.slugify
5transl('Hola, mundo'); // For backward compatibility only, will be removed in next major version
6// window.transl

CLI

1npm install transliteration -g
2
3transliterate 你好 # Ni Hao
4slugify 你好 # ni-hao
5echo 你好 | slugify -S # ni-hao

Usage

transliterate(str, [options])

Transliterate the string str and return the result. Characters which this module can't handle will default to the placeholder character(s) given in the unknown option. If it's not provided, they will be removed.

Options: (optional)

1{
2  /**
3   * Ignore a list of strings untouched
4   * @example tr('你好，世界', { ignore: ['你'] }) // 你 Hao , Shi Jie
5   */
6  ignore?: string[];
7  /**
8   * Replace a list of string / regex in the source string with the provided target string before transliteration
9   * The option can either be an array or an object
10   * @example tr('你好，世界', { replace: {你: 'You'} }) // You Hao , Shi Jie
11   * @example tr('你好，世界', { replace: [['你', 'You']] }) // You Hao , Shi Jie
12   * @example tr('你好，世界', { replace: [[/你/g, 'You']] }) // You Hao , Shi Jie
13   */
14  replace?: OptionReplaceCombined;
15  /**
16   * Same as `replace` but after transliteration
17   */
18  replaceAfter?: OptionReplaceCombined;
19  /**
20   * Decides whether or not to trim the result string after transliteration
21   * @default false
22   */
23  trim?: boolean;
24  /**
25   * Any characters not known by this library will be replaced by a specific string `unknown`
26   * @default ''
27   */
28  unknown?: string;
29  /**
30   * Fix Chinese spacing. For example, `你好` is transliterated to `Ni Hao` instead of `NiHao`. If you don't need to transliterate Chinese characters, set it to false to false to improve performance.
31   * @default true
32   */
33  fixChineseSpacing?: boolean;
34}

transliterate.config([optionsObj], [reset = false])

Bind option object globally so any following calls will use optionsObj by default. If optionsObj is not given, it will return current default option object.

1import { transliterate as tr } from 'transliteration';
2tr('你好，世界');
3// Ni Hao , Shi Jie
4tr('Γεια σας, τον κόσμο');
5// Geia sas, ton kosmo
6tr('안녕하세요, 세계');
7// annyeonghaseyo, segye
8tr('你好，世界', { replace: { 你: 'You' }, ignore: ['好'] });
9// You 好,Shi Jie
10tr('你好，世界', { replace: [['你', 'You']], ignore: ['好'] });
11// You 好,Shi Jie (option in array form)
12tr.config({ replace: [['你', 'You']], ignore: ['好'] });
13tr('你好，世界'); // You 好,Shi Jie
14console.log(tr.config());
15// { replace: [['你', 'You']], ignore: ['好'] }
16tr.config(undefined, true);
17console.log(tr.config());
18// {}

slugify(str, [options])

Convert Unicode str into a slug string, making sure it is safe to be used in an URL or in a file name.

Options: (optional)

1  /**
2   * Ignore a list of strings untouched
3   * @example tr('你好，世界', { ignore: ['你'] }) // 你 Hao , Shi Jie
4   */
5  ignore?: string[];
6  /**
7   * Replace a list of string / regex in the source string with the provided target string before transliteration
8   * The option can either be an array or an object
9   * @example tr('你好，世界', { replace: {你: 'You'} }) // You Hao , Shi Jie
10   * @example tr('你好，世界', { replace: [['你', 'You']] }) // You Hao , Shi Jie
11   * @example tr('你好，世界', { replace: [[/你/g, 'You']] }) // You Hao , Shi Jie
12   */
13  replace?: OptionReplaceCombined;
14  /**
15   * Same as `replace` but after transliteration
16   */
17  replaceAfter?: OptionReplaceCombined;
18  /**
19   * Decides whether or not to trim the result string after transliteration
20   * @default false
21   */
22  trim?: boolean;
23  /**
24   * Any characters not known by this library will be replaced by a specific string `unknown`
25   * @default ''
26   */
27  unknown?: string;
28  /**
29   * Whether the result need to be converted into lowercase
30   * @default true
31   */
32  lowercase?: boolean;
33  /**
34   * Whether the result need to be converted into uppercase
35   * @default false
36   */
37  uppercase?: boolean;
38  /**
39   * Custom separator string
40   * @default '-'
41   */
42  separator?: string;
43  /**
44   * Allowed characters.
45   * When `allowedChars` is set to `'abc'`, only characters which match `/[abc]/g` will be preserved.
46   * Other characters will all be converted to `separator`
47   * @default 'a-zA-Z0-9-_.~''
48   */
49  allowedChars?: string;
50  /**
51   * Fix Chinese spacing. For example, `你好` is transliterated to `Ni Hao` instead of `NiHao`. If you don't need to transliterate Chinese characters, set it to false to false to improve performance.
52   */
53  fixChineseSpacing?: boolean;

1slugify('你好，世界');
2// ni-hao-shi-jie
3slugify('你好，世界', { lowercase: false, separator: '_' });
4// Ni_Hao_Shi_Jie
5slugify('你好，世界', {
6  replace: { 你好: 'Hello', 世界: 'world' },
7  separator: '_',
8});
9// hello_world
10slugify('你好，世界', {
11  replace: [
12    ['你好', 'Hello'],
13    ['世界', 'world'],
14  ],
15  separator: '_',
16}); // replace option in array form)
17// hello_world
18slugify('你好，世界', { ignore: ['你好'] });
19// 你好shi-jie

slugify.config([optionsObj], [reset = false])

Bind option object globally so any following calls will use optionsObj by default. If optionsObj is not given, it will return current default option object.

1slugify.config({ lowercase: false, separator: '_' });
2slugify('你好，世界');
3// Ni_Hao_Shi_Jie
4console.log(slugify.config());
5// { lowercase: false, separator: "_" }
6slugify.config({ replace: [['你好', 'Hello']] });
7slugify('你好, world!');
8// This equals slugify('你好, world!', { replace: [['你好', 'Hello']] });
9console.log(slugify.config());
10// { replace: [['你好', 'Hello']] }
11slugify.config(undefined, true);
12console.log(slugify.config());
13// {}

CLI Usage

➜  ~ transliterate --help
Usage: transliterate <unicode> [options]

Options:
  --version      Show version number                                                       [boolean]
  -u, --unknown  Placeholder for unknown characters                           [string] [default: ""]
  -r, --replace  Custom string replacement                                     [array] [default: []]
  -i, --ignore   String list to ignore                                         [array] [default: []]
  -S, --stdin    Use stdin as input                                       [boolean] [default: false]
  -h, --help                                                                               [boolean]

Examples:
  transliterate "你好, world!" -r 好=good -r          Replace `,` with `!`, `world` with `shijie`.
  "world=Shi Jie"                                     Result: Ni good, Shi Jie!
  transliterate "你好，世界!" -i 你好 -i ，           Ignore `你好` and `，`.
                                                      Result: 你好，Shi Jie !

➜  ~ slugify --help
Usage: slugify <unicode> [options]

Options:
  --version        Show version number                                                     [boolean]
  -U, --unknown    Placeholder for unknown characters                         [string] [default: ""]
  -l, --lowercase  Returns result in lowercase                             [boolean] [default: true]
  -u, --uppercase  Returns result in uppercase                            [boolean] [default: false]
  -s, --separator  Separator of the slug                                     [string] [default: "-"]
  -r, --replace    Custom string replacement                                   [array] [default: []]
  -i, --ignore     String list to ignore                                       [array] [default: []]
  -S, --stdin      Use stdin as input                                     [boolean] [default: false]
  -h, --help                                                                               [boolean]

Examples:
  slugify "你好, world!" -r 好=good -r "world=Shi     Replace `,` with `!` and `world` with
  Jie"                                                `shijie`.
                                                      Result: ni-good-shi-jie
  slugify "你好，世界!" -i 你好 -i ，                 Ignore `你好` and `，`.
                                                      Result: 你好，shi-jie

Caveats

Currently, transliteration only supports 1 to 1 code map (from Unicode to Latin). It is the simplest way to implement, but there are some limitations when dealing with polyphonic characters. It does not work well with all languages, please test all possible situations before using it. Some known issues are:

• Chinese: Polyphonic characters are not always transliterated correctly. Alternative: pinyin.

• Japanese: Most Japanese Kanji characters are transliterated into Chinese Pinyin because of the overlapped code map in Unicode. Also there are many polyphonic characters in Japanese which makes it impossible to transliterate Japanese Kanji correctly without tokenizing the sentence. Consider using kuroshiro for a better Kanji -> Romaji conversion.

• Thai: Currently it is not working. If you know how to fix it, please comment on this issue.

• Cyrillic: Cyrillic characters are overlapped between a few languages. The result might be inaccurate in some specific languages, for example Bulgarian.

If you find any other issues, please raise a ticket.

License

MIT