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.
Demo
example.html
Installation
Node.js
npm install transliteration --save
import { transliterate as tr, slugify } from 'transliteration';
tr('你好, world!');
slugify('你好, world!');
Browser
bower install transliteration
<html>
<head>
<script src="bower_components/transliteration/transliteration.min.js"></script>
</head>
<body>
<script>
transl('你好, world!');
slugify('你好, world!');
</script>
</body>
</html>
Browser support
transliteration
has a good browser compatibility with all major browsers (including IE 6-8 if used with es5-shim
).
CLI
npm install transliteration -g
transliterate 你好
slugify 你好
ReactNative
import { transliterate, slugify } from 'transliteration/src/main/browser';
Breaking changes
###1.0.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:
- The
options
parameter of transliterate
now is an Object
(In 0.1.x it's a string unknown
). - Added
transliterate.config
and slugify.config
. - Unknown string will be transliterated as
[?]
instead of ?
. - In browser, global variables have been changed to
window.transl
and windnow.slugify
. Other global variables are removed.
Usage
transliterate(str, [options])
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: (optionable)
{
unknown: '[?]',
replace: { source1: target1, source2: target2, ... },
replace: [[source1, target1], [source2, target2], ... ],
ignore: [str1, str2]
}
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!');
Example
import { transliterate as tr } from 'transliteration';
tr('你好,世界');
tr('Γεια σας, τον κόσμο');
tr('안녕하세요, 세계');
tr('你好,世界', { replace: {你: 'You'}, ignore: ['好'] })
tr('你好,世界', { replace: [['你', 'You']], ignore: ['好'] })
tr.config({ replace: [['你', 'You']], ignore: ['好'] });
tr('你好,世界')
console.log(tr.config());
slugify(str, [options])
Converts unicode string to slugs. So it can be safely used in URL or file name.
Options: (optionable)
{
lowercase: false,
separator: '-',
replace: { source1: target1, source2: target2, ... },
replace: [[source1, target1], [source2, target2], ... ],
ignore: [str1, str2]
}
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!');
Example:
import { slugify } from 'transliteration';
slugify('你好,世界');
slugify('你好,世界', { lowercase: false, separator: '_' });
slugify('你好,世界', { replace: {你好: 'Hello', 世界: 'world'}, separator: '_' });
slugify('你好,世界', { replace: [['你好', 'Hello'], ['世界', 'world']], separator: '_' });
slugify('你好,世界', { ignore: ['你好'] });
slugify.config({ lowercase: false, separator: '_' });
slugify('你好,世界');
console.log(slugify.config());
Usage in browser
transliteration
can be loaded as a 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');
slugify('Hello, 世界');
If the name of the variables conflict with other libraries in your project or you prefer not to use global variables, you can then call noConfilict() before loading other libraries which contails the possible conflict.:
Load the library globally
var tr = transl.noConflict();
console.log(transl);
tr('你好, World');
var slug = slugify.noConfilict();
slug('你好, World');
console.log(slugify);
Usage in command line
➜ ~ 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: []]
-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: []]
-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
Caveats
transliteration
supports almost all common languages whereas there might be quirks in some specific languages. For example Kanji characters in Japanese will be translierated as Chinese Pinyin. I couldn't find a better way to distinguash Chinese Hanzi and Japanese Kanji. So if you would like to romanize Japanese Kanji, please consider kuroshiro.
If you find any issues, please raise a github issue. Thanks!
License
MIT