Transliterations
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.
Installation
npm install transliterations --save
; ; // Ni Hao , world!; // ni-hao-world
Browser support
transliterations
has a good browser compatibility with all major browsers (including IE 6-8 if used with es5-shim
).
CLI
npm install transliterations -g transliterate 你好 # Ni Hao slugify 你好 # ni-hao echo 你好 | slugify -S # ni-hao
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: (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;; // Result: 'Hello, world!'. This equals transliterate('你好, world!', { replace: [['你好', 'Hello']] });
Example
;; // Ni Hao , Shi Jie; // Geia sas, ton kosmo; // annyeonghaseyo, segye // You 好, Shi Jie // You 好, Shi Jie (option in array form)// or use configurationstr; // You 好, Shi Jie// get configurationsconsole;
slugify(str, [options])
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;; // Result: 'hello-world'. This equals slugify('你好, world!', { replace: [['你好', 'Hello']] });
Example:
;; // ni-hao-shi-jie; // Ni_Hao_Shi_Jie; // hello_world; // hello_world (option in array form); // 你好shi-jie// or use configurationsslugify;; // Ni_Hao_Shi_Jie// get configurationsconsole;
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: []]
-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
Caveats
transliterations
supports almost all common languages whereas there might be quirks in some specific languages. For example, Kanji characters in Japanese will be transliterated as Chinese Pinyin. I couldn't find a better way to distinguish 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