doc(us_EN): Add english document

README-us_EN.md

@@ -0,0 +1,184 @@
+
+# PinYin for Han （汉字）
+
+---
+
+[![NPM version][npm-badge]][npm-url]
+[![spm version][spm-badge]][spm-url]
+[![Build Status][travis-badge]][travis-url]
+[![Coverage Status][coveralls-badge]][coveralls-url]
+
+[npm-badge]: https://img.shields.io/npm/v/pinyin.svg?style=flat
+[npm-url]: https://www.npmjs.com/package/pinyin
+[spm-badge]: http://spmjs.io/badge/pinyin
+[spm-url]: http://spmjs.io/package/pinyin
+[travis-badge]: https://travis-ci.org/hotoo/pinyin.svg
+[travis-url]: https://travis-ci.org/hotoo/pinyin
+[coveralls-badge]: https://coveralls.io/repos/hotoo/pinyin/badge.svg?branch=master
+[coveralls-url]: https://coveralls.io/r/hotoo/pinyin
+
+[中文文档](README.md)
+
+Convert Han to pinyin. useful for phonetic notation, sorting, and searching.
+
+> Note: This module both support Node and Web browser.
+>
+> Python version see [mozillazg/python-pinyin](https://github.com/mozillazg/python-pinyin)
+
+---
+
+## Feature
+
+* Segmentation for heteronym words.
+* Support Traditional and Simplified Chinese.
+* Support multiple pinyin style.
+
+## Install
+
+via npm:
+
+```bash
+npm install pinyin
+```
+
+via spm:
+
+```bash
+spm install pinyin
+```
+
+## Usage
+
+for developer:
+
+```js
+var pinyin = require("pinyin");
+
+console.log(pinyin("中心"));    // [ [ 'zhōng' ], [ 'xīn' ] ]
+console.log(pinyin("中心", {
+  heteronym: true                // Enable heteronym mode.
+}));                            // [ [ 'zhōng', 'zhòng' ], [ 'xīn' ] ]
+console.log(pinyin("中心", {
+  heteronym: true,              // Enable heteronym mode.
+  segment: true                 // Enable Chinese words eegmentation, fix most heteronym problem.
+}));                            // [ [ 'zhōng' ], [ 'xīn' ] ]
+console.log(pinyin("中心", {
+  style: pinyin.STYLE_INITIALS, // Setting pinyin style.
+  heteronym: true
+}));                            // [ [ 'zh' ], [ 'x' ] ]
+```
+
+for cli:
+
+```bash
+$ pinyin 中心
+zhōng xīn
+$ pinyin -h
+```
+
+## API
+
+### `<Array> pinyin(words[, options])`
+
+Convert Han （汉字） to pinyin.
+
+`options` argument is optional, for sepcify heteronym mode and pinyin styles.
+
+Return a `Array<Array<String>>`. If one of Han is heteronym word, it would be
+have multiple pinyin.
+
+## Options
+
+#### `<Boolean> options.segment`
+
+Enable Chinese word segmentation. Segmentation is helpful for fix heteronym
+problem, but performance will be more slow, and need more CPU and memory.
+
+Default is `false`.
+
+### `<Boolean> options.heteronym`
+
+Enable or disable heteronym mode. default is disabled, `false`.
+
+### `<Object> options.style`
+
+Specify pinyin style. please use static properties like `STYLE_*`.
+default is `.STYLE_TONE`. see Static Property for more.
+
+## Static Property
+
+### `.STYLE_NORMAL`
+
+Normal mode.
+
+Example: `pin yin`
+
+### `.STYLE_TONE`
+
+Tone style, this is default.
+
+Example: `pīn yīn`
+
+### `.STYLE_TONE2`
+
+Another tone style, use postfix number [0-4].
+
+Example: `pin1 yin1`
+
+### `.STYLE_INITIALS`
+
+Initial consonant (of a Chinese syllable).
+
+Example: pinyin of `中国` is `zh g`
+
+Note: when a Han （汉字） without initial consonant, will convert to empty string.
+
+### `.STYLE_FIRST_LETTER`
+
+First letter style.
+
+Example: `p y`
+
+
+## Test
+
+```
+npm test
+```
+
+## Q&A
+
+### What's the different Node version and Web version?
+
+`pinyin` support Node and Web browser now, the API and usage is complete same.
+
+But the Web version is simple than Node version. Just frequently-used dict,
+without segmentation, and the dict is compress for web.
+
+Because of Traditional and Segmentation, the convert result will be not complete same.
+and the test case have some different too.
+
+| Feature      | Web version                     | Node version                     |
+|--------------|---------------------------------|----------------------------------|
+| Dict         | Frequently-used Dict, Compress. | Complete Dict, without Compress. |
+| Segmentation | NO                              | Segmentation options.            |
+| Traditional  | NO                              | Full Traditional support.        |
+
+
+## Donate
+
+If this module is helpful for you, please Star this repository.
+
+And you have chioce donate to me via Aliapy or WeChat:
+
+![Alipay:hotoo.cn@gmail.com, WeChat:hotoome](http://hotoo.me/images/donate-hotoo.png)
+
+or donate my dear wife [@lizzie](https://github.com/lizzie) direct:
+
+![Alipay:shenyan1985@gmail.com, WeChat:SunsetSunrising](http://hotoo.me/images/donate-lizzie.png)
+
+The two donate way wile have the same result.
+
+## License
+
+[MIT](http://hotoo.mit-license.org/)

README.md

@@ -16,6 +16,8 @@
 [coveralls-badge]: https://coveralls.io/repos/hotoo/pinyin/badge.svg?branch=master
 [coveralls-url]: https://coveralls.io/r/hotoo/pinyin
 
+[English Documention](README-us_EN.md)
+
 转换中文字符为拼音。可以用于汉字注音、排序、检索。
 
 > 注：这个版本同时支持在 Node 和 Web 浏览器环境运行，
@@ -40,7 +42,7 @@ via npm:
 npm install pinyin
 ```
 
-via spm3:
+via spm:
 
 ```bash
 spm install pinyin
@@ -86,52 +88,54 @@ options 是可选的，可以设定拼音风格，或打开多音字选项。
 返回二维数组，第一维每个数组项位置对应每个中文字符串位置。
 第二维是各个汉字的读音列表，多音字会有多个拼音项。
 
-### 参数 `<Boolean> options.segment`
+## 参数
+
+### `<Boolean> options.segment`
 
 是否启用分词模式，中文分词有助于极大的降低多音字问题。
 但性能会极大的下降，内存也会使用更多。
 
-### 参数 `<Boolean> options.heteronym`
+### `<Boolean> options.heteronym`
 
 是否启用多音字模式，默认关闭。
 
 关闭多音字模式时，返回每个汉字第一个匹配的拼音。
 
 启用多音字模式时，返回多音字的所有拼音列表。
 
-### 参数 `<Object> options.style`
+### `<Object> options.style`
 
 指定拼音 风格。可以通过以下几种 `STYLE_` 开头的静态属性进行指定。
 
-### 静态属性 `.STYLE_NORMAL`
+## 静态属性
+
+### `.STYLE_NORMAL`
 
 普通风格，即不带音标。
 
 如：`pin yin`
 
-### 静态属性 `.STYLE_TONE`
+### `.STYLE_TONE`
 
 声调风格，拼音声调在韵母第一个字母上。
 
 注：这是默认的风格。
 
 如：`pīn yīn`
 
-### 静态属性 `.STYLE_TONE2`
+### `.STYLE_TONE2`
 
 声调风格 2，即拼音声调在各个拼音之后，用数字 [0-4] 进行表示。
 
 如：`pin1 yin1`
 
-### 静态属性 `.STYLE_INITIALS`
+### `.STYLE_INITIALS`
 
 声母风格，只返回各个拼音的声母部分。
 
 如：`中国` 的拼音 `zh g`
 
-例外，对于只有韵母的汉字（如『爱、啊』等），会先转成不带音标的普通风格。
-
-### 静态属性 `.STYLE_FIRST_LETTER`
+### `.STYLE_FIRST_LETTER`
 
 首字母风格，只返回拼音的首字母部分。