transliteration

Transliteration

A universal Unicode to Latin transliteration and slug generation library. Designed for cross-platform compatibility with comprehensive language support.

Live Demo →

Table of Contents

• Features
• Latin-Only Mode
• Compatibility
• Installation
• Usage
  • transliterate()
  • slugify()
  • CLI
• Known Issues
• License

Features

• Unicode Transliteration — Convert characters from any writing system to Latin equivalents
• Slug Generation — Create URL-safe and filename-safe strings from Unicode text
• Highly Configurable — Extensive options for custom replacements, ignored characters, and output formatting
• Cross-Platform — Runs seamlessly in Node.js, browsers, and command-line environments
• TypeScript Ready — Full type definitions included out of the box
• Zero Dependencies — Lightweight with no external runtime dependencies

Latin-Only Mode

For applications that only need to transliterate Latin-based scripts (Western European languages), you can use the lightweight Latin-only build for significantly smaller bundle size:

// Full build: ~186 KB (all scripts including CJK, Korean, etc.)
import { transliterate, slugify } from 'transliteration';

// Latin-only build: ~5 KB (Basic Latin + Latin Extended only)
import { transliterate, slugify } from 'transliteration/latin';

The Latin-only build supports:

• Basic ASCII (U+0000-U+007F)
• Latin-1 Supplement (U+0080-U+00FF)
• Latin Extended-A (U+0100-U+017F)
• Latin Extended-B (U+0180-U+024F)

This is ideal for applications that only handle Western European languages and want to minimize bundle size.

Compatibility

• Node.js: v20.0.0 or higher
• Browsers: All modern browsers (Chrome, Firefox, Safari, Edge)
• Mobile: React Native
• Other: Web Workers, CLI

Installation

Node.js / React Native

npm install transliteration

TypeScript: Type definitions are bundled with this package. Do not install @types/transliteration.

Quick Start:

import { transliterate as tr, slugify } from 'transliteration';

// Transliteration
tr('你好, world!');  // => 'Ni Hao , world!'

// Slugify
slugify('你好, world!');  // => 'ni-hao-world'

Browser (CDN)

UMD Build (Global Variables)

<script src="https://cdn.jsdelivr.net/npm/transliteration@2/dist/browser/bundle.umd.min.js"></script>
<script>
  // Available as global variables
  transliterate('你好, World');  // => 'Ni Hao , World'
  slugify('Hello, 世界');       // => 'hello-shi-jie'
  
  // Legacy method (will be removed in next major version)
  transl('Hola, mundo');       // => 'hola-mundo'
</script>

ES Module

<script type="module">
  import { transliterate } from 'https://cdn.jsdelivr.net/npm/transliteration@2/dist/browser/bundle.esm.min.js';
  console.log(transliterate('你好'));  // => 'Ni Hao'
</script>

CLI

# Global installation
npm install transliteration -g

# Basic usage
transliterate 你好                # => Ni Hao
slugify 你好                      # => ni-hao

# Using stdin
echo 你好 | slugify -S           # => ni-hao

Usage

transliterate(str, [options])

Converts Unicode characters in the input string to their Latin equivalents. Unrecognized characters are replaced with the unknown placeholder or removed if no placeholder is specified.

Options

Option	Type	Default	Description
ignore	string[]	[]	Strings to preserve without transliteration
replace	object or array	{}	Custom replacements applied before transliteration
replaceAfter	object or array	{}	Custom replacements applied after transliteration
trim	boolean	false	Trim leading and trailing whitespace from result
unknown	string	''	Replacement character for unrecognized Unicode
fixChineseSpacing	boolean	true	Insert spaces between transliterated Chinese characters

Example

import { transliterate as tr } from 'transliteration';

// Basic usage
tr('你好，世界');                  // => 'Ni Hao , Shi Jie'
tr('Γεια σας, τον κόσμο');        // => 'Geia sas, ton kosmo'
tr('안녕하세요, 세계');             // => 'annyeonghaseyo, segye'

// With options
tr('你好，世界', { 
  replace: { 你: 'You' }, 
  ignore: ['好'] 
});                              // => 'You 好, Shi Jie'

// Array form of replace option
tr('你好，世界', { 
  replace: [['你', 'You']], 
  ignore: ['好'] 
});                              // => 'You 好, Shi Jie'

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

Sets global default options for all subsequent transliterate() calls. When called without arguments, returns the current configuration. Pass reset = true to restore factory defaults.

// Set global configuration
tr.config({ replace: [['你', 'You']], ignore: ['好'] });

// All calls will use this configuration
tr('你好，世界');                  // => 'You 好, Shi Jie'

// View current configuration
console.log(tr.config());        // => { replace: [['你', 'You']], ignore: ['好'] }

// Reset to defaults
tr.config(undefined, true);
console.log(tr.config());        // => {}

slugify(str, [options])

Transforms Unicode text into a URL-safe and filename-safe slug string.

Options

Option	Type	Default	Description
ignore	string[]	[]	Strings to preserve without transliteration
replace	object or array	{}	Custom replacements applied before transliteration
replaceAfter	object or array	{}	Custom replacements applied after transliteration
trim	boolean	false	Trim leading and trailing whitespace from result
unknown	string	''	Replacement character for unrecognized Unicode
lowercase	boolean	true	Convert output to lowercase
uppercase	boolean	false	Convert output to uppercase
separator	string	-	Word separator character
allowedChars	string	a-zA-Z0-9-_.~'	Regex character class for permitted characters
fixChineseSpacing	boolean	true	Insert spaces between transliterated Chinese characters

Example

// Basic usage
slugify('你好，世界');                // => 'ni-hao-shi-jie'

// With options
slugify('你好，世界', { 
  lowercase: false, 
  separator: '_' 
});                                // => 'Ni_Hao_Shi_Jie'

// Using replace option
slugify('你好，世界', {
  replace: { 
    你好: 'Hello', 
    世界: 'world' 
  },
  separator: '_'
});                                // => 'hello_world'

// Using ignore option
slugify('你好，世界', { 
  ignore: ['你好'] 
});                                // => '你好shi-jie'

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

Sets global default options for all subsequent slugify() calls. When called without arguments, returns the current configuration. Pass reset = true to restore factory defaults.

// Set global configuration
slugify.config({ lowercase: false, separator: '_' });

// All calls will use this configuration
slugify('你好，世界');              // => 'Ni_Hao_Shi_Jie'

// View current configuration
console.log(slugify.config());    // => { lowercase: false, separator: "_" }

// Reset to defaults
slugify.config(undefined, true);
console.log(slugify.config());    // => {}

CLI Usage

Transliterate Command

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     Show help information                             [boolean]

Examples:
  transliterate "你好, world!" -r 好=good -r "world=Shi Jie"
  transliterate "你好，世界!" -i 你好 -i ，

Slugify Command

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       Show help information                           [boolean]

Examples:
  slugify "你好, world!" -r 好=good -r "world=Shi Jie"
  slugify "你好，世界!" -i 你好 -i ，

Known Issues

This library uses 1-to-1 Unicode code point mapping, which provides broad language coverage but has inherent limitations with context-dependent characters (e.g., polyphonic characters where pronunciation varies by context). Thorough testing with your target languages is recommended before production use.

Language-Specific Limitations:

Language	Issue	Alternative
Chinese	Polyphonic characters may not transliterate correctly	pinyin
Japanese	Kanji characters often convert to Chinese Pinyin due to Unicode overlap	kuroshiro
Thai	Not working properly	Issue #67
Cyrillic	May be inaccurate for specific languages like Bulgarian	-

For other issues or feature requests, please open an issue.

License

MIT

Similar packages

Other packages similar to transliteration

transliterator

The 'transliterator' package provides similar functionality for converting text between different scripts. It supports a wide range of languages and offers customizable transliteration schemes. Compared to 'transliteration', it may offer more flexibility in defining custom rules.

unidecode

The 'unidecode' package is another alternative for transliterating Unicode text to ASCII. It is particularly known for its simplicity and ease of use. However, it may not support as many languages or offer as much customization as 'transliteration'.

diacritics

The 'diacritics' package focuses on removing diacritical marks from text, converting it to a simpler form. While it doesn't offer full transliteration capabilities, it is useful for normalizing text. It is more specialized compared to 'transliteration'.