transliteration
Advanced tools
Unicode to ACSII transliteration / slugify module for node.js, browser, Web Worker, ReactNative and CLI.
The 'transliteration' npm package provides utilities for converting text between different scripts, particularly useful for converting non-Latin scripts to Latin scripts. It supports various transliteration schemes and can handle a wide range of languages.
Basic Transliteration
This feature allows you to convert text from non-Latin scripts to Latin scripts. In this example, Chinese characters are transliterated to their Latin equivalents.
const { transliterate } = require('transliteration');
const text = '你好，世界';
const result = transliterate(text);
console.log(result); // Output: 'Ni Hao , Shi Jie'Slugify
This feature converts text into a URL-friendly slug. It is particularly useful for creating SEO-friendly URLs from non-Latin scripts.
const { slugify } = require('transliteration');
const text = '你好，世界';
const result = slugify(text);
console.log(result); // Output: 'ni-hao-shi-jie'Custom Transliteration
This feature allows you to define custom mappings for transliteration. In this example, specific Cyrillic characters are mapped to their Latin equivalents.
const { transliterate } = require('transliteration');
const text = 'Привет, мир';
const customMap = { 'и': 'i', 'е': 'e', 'в': 'v' };
const result = transliterate(text, { customMap });
console.log(result); // Output: 'Privet, mir'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.
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'.
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'.
Transliteration / slugify module for node.js, browser, Web Worker, ReactNative and CLI. It provides the ability to transliterate UTF-8 characters into corresponding pure ASCII; so they can be safely displayed, used as URL slugs or file names.
npm install transliteration --save
import { transliterate as tr, slugify } from 'transliteration';
tr('你好, world!'); // Ni Hao , world!
slugify('你好, world!'); // ni-hao-world
CDN:
<script src="https://unpkg.com/transliteration/lib/browser/transliteration.min.js"></script>
Bower:
# Install bower if not already installed
# npm install bower -g
bower install transliteration
<html>
<head>
<script src="bower_components/transliteration/transliteration.min.js"></script>
</head>
<body>
<script>
transl('你好, world!'); // Ni Hao , world!
slugify('你好, world!'); // ni-hao-world
</script>
</body>
</html>
transliteration has a good browser compatibility with all major browsers (including IE 6-8 if used with es5-shim).
npm install transliteration -g
transliterate 你好 # Ni Hao
slugify 你好 # ni-hao
echo 你好 | slugify -S # ni-hao
import { transliterate, slugify } from 'transliteration/src/main/browser';
bower support is dropped. Please use CDN or a js bundler like webpack.
Added support for TypeScript. #77
Since version 1.5.0, transliteration module requires minimum node version v6.0.
Please note that the code has been entirely refactored since version 1.0.0. Be careful when you plan to upgrade from v0.1.x or v0.2.x to v1.0.x
Changes:
options parameter of transliterate now is an Object (In 0.1.x it's a string unknown).transliterate.config and slugify.config.[?] instead of ?.window.transl and windnow.slugify. Other global variables are removed.Transliterates the string str and return the result. Characters which this module doesn't recognise will be defaulted to the placeholder from the unknown argument in the configuration option, defaults to [?].
Options: (optional)
{
/* Unicode characters that are not in the database will be replaced with `unknown` */
unknown: '[?]', // default: [?]
/* Custom replacement of the strings before transliteration */
replace: { source1: target1, source2: target2, ... }, // Object form of argument
replace: [[source1, target1], [source2, target2], ... ], // Array form of argument
/* Strings in the ignore list will be bypassed from transliteration */
ignore: [str1, str2] // default: []
}
transliterate.config([optionsObj])
Bind options globally so any following calls will be using optoinsObj by default. If optionsObj argument is omitted, it will return current default option object.
transliterate.config({ replace: [['你好', 'Hello']] });
transliterate('你好, world!'); // Result: 'Hello, world!'. This equals transliterate('你好, world!', { replace: [['你好', 'Hello']] });
Example
import { transliterate as tr } from 'transliteration';
tr('你好，世界'); // Ni Hao , Shi Jie
tr('Γεια σας, τον κόσμο'); // Geia sas, ton kosmo
tr('안녕하세요, 세계'); // annyeonghaseyo, segye
tr('你好，世界', { replace: {你: 'You'}, ignore: ['好'] }) // You 好, Shi Jie
tr('你好，世界', { replace: [['你', 'You']], ignore: ['好'] }) // You 好, Shi Jie (option in array form)
// or use configurations
tr.config({ replace: [['你', 'You']], ignore: ['好'] });
tr('你好，世界') // You 好, Shi Jie
// get configurations
console.log(tr.config());
Converts Unicode string to slugs. So it can be safely used in URL or file name.
Options: (optional)
{
/* Whether to force slags to be lowercased */
lowercase: false, // default: true
/* Separator of the slug */
separator: '-', // default: '-'
/* Custom replacement of the strings before transliteration */
replace: { source1: target1, source2: target2, ... },
replace: [[source1, target1], [source2, target2], ... ], // default: []
/* Strings in the ignore list will be bypassed from transliteration */
ignore: [str1, str2] // default: []
}
If options is not provided, it will use the above default values.
slugify.config([optionsObj])
Bind options globally so any following calls will be using optoinsObj by default. If optionsObj argument is omitted, it will return current default option object.
slugify.config({ replace: [['你好', 'Hello']] });
slugify('你好, world!'); // Result: 'hello-world'. This equals slugify('你好, world!', { replace: [['你好', 'Hello']] });
Example:
import { slugify } from 'transliteration';
slugify('你好，世界'); // ni-hao-shi-jie
slugify('你好，世界', { lowercase: false, separator: '_' }); // Ni_Hao_Shi_Jie
slugify('你好，世界', { replace: {你好: 'Hello', 世界: 'world'}, separator: '_' }); // hello_world
slugify('你好，世界', { replace: [['你好', 'Hello'], ['世界', 'world']], separator: '_' }); // hello_world (option in array form)
slugify('你好，世界', { ignore: ['你好'] }); // 你好shi-jie
// or use configurations
slugify.config({ lowercase: false, separator: '_' });
slugify('你好，世界'); // Ni_Hao_Shi_Jie
// get configurations
console.log(slugify.config());
transliteration can be loaded as an AMD / CommonJS module, or as global variables (UMD).
When using it in the browser, by default it will create global variables under window object:
transl('你好, World'); // window.transl
// or
slugify('Hello, 世界'); // window.slugify
If the variable names conflict with other libraries in your project or you prefer not to use global variables, use noConfilict() before loading libraries which contain the conflicting variables.:
Load the library globally
var tr = transl.noConflict();
console.log(transl); // undefined
tr('你好, World'); // Ni Hao , World
var slug = slugify.noConfilict();
slug('你好, World'); // ni-hao-world
console.log(slugify); // undefined
➜ ~ 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 Show help [boolean]
Examples:
transliterate "你好, world!" -r 好=good -r Replace `,` into `!` and `world` into
"world=Shi Jie" `shijie`.
Result: Ni good, Shi Jie!
transliterate "你好，世界!" -i 你好 -i ， Ignore `你好` and `，`.
Result: 你好，Shi Jie !
Result: 你好,world!
➜ ~ slugify --help
Usage: slugify <unicode> [options]
Options:
--version Show version number [boolean]
-l, --lowercase Use lowercase [boolean] [default: true]
-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 [boolean]
Examples:
slugify "你好, world!" -r 好=good -r "world=Shi Replace `,` into `!` and `world` into
Jie" `shijie`.
Result: ni-good-shi-jie
slugify "你好，世界!" -i 你好 -i ， Ignore `你好` and `，`.
Result: 你好，shi-jie
Currently, transliteration uses 1 to 1 character map (from Unicode to Latin) under the hood. It is the simplest way to implement, but it has some limitations when dealing with polyphonic characters and languages which share overlapped character sets. It does not work well in some specific languages when the same characters can be transliterated differently when they are placed at different places. Some of the issues are listed below:
Chinese: Polyphonic characters are not always transliterated correctly. Alternative: pinyinlite.
Japanese: With transliteration, most Japanese Kanji characters are transliterated to Chinese Pinyin because of their overlapping of characters in Unicode. Also there are many polyphonic characters. without doing a word splitting or word mapping, it's impossible to transliterate Kanji accurately. Alternative: kuroshiro.
Thai: Currently it is not working. There seems no working open source project I can directly copy code from. I found some articles explaining the how to transliterate Thai though. I would appreciate if anyone who is interested implementing it can lend a hand. See: #67.
Cylic Cylic characters are overlapped between a few languages. The result might be inaccurate in some specific languages, for example Bulgarian.
If you there's any other issues, please raise a ticket.
BrowserStack is a fantastic service for testing your web applications in tons of different real browsers and mobile devices. transliteration uses BrowserStack to do unit test in different browsers.
MIT
FAQs
Unicode to ACSII transliteration / slugify module for node.js, browser, Web Worker, ReactNative and CLI.
We found that transliteration demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.
Security News
The Ultralytics' PyPI Package was compromised four times in one weekend through GitHub Actions cache poisoning and failure to rotate previously compromised API tokens.