han/readme.md

a module for tanslating Chinese(汉字) into pinyin

# Han(汉)

[![Build Status](https://travis-ci.org/sofish/han.png)](https://travis-ci.org/sofish/han)

a module for tanslating Chinese(汉字) into pinyin.

## Installation

```bash
$ npm install han
```

## Usage

### 1. han.letter()

```js
han.letter(chinese ,[separator ,[callback(err, data)])
```
Use the `letter` method to translate Chinese in to english letter:

```js
var han = require('han');

han.letter('中文') // zhongwen
han.letter('中文', '-') // zhong-wen
han.letter('中文', function(err, result){
  console.log(result) // zhongwen
})
```

The `letter` method has 3 params by default, they can all be _**optional**_, it depends on you(^^). follow the message below, you can also find it at [lib/translate.js](https://github.com/sofish/han/blob/master/lib/translate.js):

```js
/* @param `chinese` {String} Chinese word
 * @param [optional] `separator` {String} separator for the letters
 * @param [optional] `callback(err, result)` {Function} if a callback is specified,
 *   the program will use an async way to do the translation 
 */
```

### 2. han.pinyin(chinese)

User the `pinyin` method to translate Chinese into Pinyin(letters with notation):

```js
han.pinyin('中文') // [ [ 'zhōng', 'zhòng' ], [ 'wén', 'wèn' ] ]

// mixin are allowed, like:
han.pinyin('My Chinese name is 小鱼(sofish)');
// [ 'My Chinese name is ', [ 'xǐao' ], [ 'yú' ], '(sofish)' ]

// also running with messy code, see the testcase below
```

#### __WHY__ the return value is an array?

Beause that a Chinese word always having more than one pronunciation. You may want to allow users to correct your output that is generated by your program in an automatic way(like google?! yep!).

## Testcase

```sh
$ npm install han
# or git clone git://github.com/sofish/han.git

$ cd node_modules/han && node testcase.js
```

## Translating Messy Code

Messy code? orginal file is here [testcase.js](https://github.com/sofish/han/blob/master/testcase.js):
```js
var han = require('han');

console.log('orginal：要实现 Speaker Deck 那种中文转拼音的')
console.log(han.letter('要实现 Speaker Deck 那种中文转拼音的', '-'), '\n')
// orginal：要实现 Speaker Deck 那种中文转拼音的
// yao-shi-xian-speaker-deck-na-zhong-zhong-wen-zhuan-pin-yin-de

han.letter('中aaaaa中¢∞§¶•誩aa文喳aa', function(err, result){
  if(err) throw err;
  console.log('orginal：中aaaaa中¢∞§¶•誩aa文喳aa')
  console.log('callback：' + result, '\n')
  // orginal：中aaaaa中¢∞§¶•誩aa文喳aa
  // callback：zhong aaaaa 4e2da2 221ea7b6 2022 jing aa wen zha aa
});

han.letter('中EnglishWords¢∞§¶•ªº文', '-', function(err, result){
  console.log('orginal：中EnglishWords¢∞§¶•ªº文')
  console.log('callback：' + result)
  // original：中EnglishWords¢∞§¶•ªº文
  // callback：zhong-englishwords-221ea7b6-2022aaba-wen
});


console.log('original: My Chinese name is 小鱼(sofish)')
console.log(han.pinyin('My Chinese name is 小鱼(sofish)'))
// original: My Chinese name is 小鱼(sofish)
// [ 'My Chinese name is ', [ 'xǐao' ], [ 'yú' ], '(sofish)' ]

console.log('original: #$%^&*中23¢∞§¶•ª52849文@#$%^&*(意思，还有英文：english')
console.log(han.pinyin('#$%^&*中23¢∞§¶•ª52849文@#$%^&*(意思，还有英文：english'))
// original: #$%^&*中23¢∞§¶•ª52849文@#$%^&*(意思，还有英文：english
// [ '#$%^&*', [ 'zhōng', 'zhòng' ], '23¢∞§¶•ª52849', [ 'wén', 'wèn' ],
//  '@#$%^&*(', [ 'yì' ], [ 'sī', 'sì', 'sāi' ], '，', [ 'húan', 'hái', 'xúan' ],
//  [ 'yǒu', 'yòu' ], [ 'yīng', 'yāng' ], [ 'wén', 'wèn' ], '：english' ]
```

## License

Licensed under [MIT](https://github.com/sofish/han/blob/master/LICENSE).


## Contributers:

Specail thank to [fayland](https://github.com/fayland/perl-lingua-han/tree/master/Lingua-Han-PinYin/lib/Lingua/Han/PinYin) for providing the unicode table of Chinese.