Skip to content


Subversion checkout URL

You can clone with
Download ZIP
node.js iconv bindings - text recoding for fun and profit!
C++ JavaScript
Pull request Compare This branch is 21 commits ahead, 66 commits behind bnoordhuis:master.


Text recoding in JavaScript for fun and profit!
Powerd by GNU libiconv-1.9.1
The libiconv-1.9.1-ja-patch-1.diff.gz was applied.
It will solve the problem to Japanese.

in Japanese:
GNU libiconv-1.9.1をベースにlibiconv-1.9.1-ja-patch-1.diff.gzを適用したものを利用しています。

Installing with npm

npm install iconv-jp

Note that the npm-ified version of node-iconv only works with node.js >= v0.3.0.


To compile and install the module, type:

make install NODE_PATH=/path/to/nodejs

NODE_PATH will default to /usr/local if omitted.

Note that you do not need to have a copy of libiconv installed to use this module.


Encode from one character encoding to another:

// convert from UTF-8 to ISO-8859-1
var Buffer = require('buffer').Buffer;
var Iconv  = require('iconv').Iconv;
var assert = require('assert');

var iconv = new Iconv('UTF-8', 'ISO-8859-1');
var buffer = iconv.convert('Hello, world!');
var buffer2 = iconv.convert(new Buffer('Hello, world!'));
assert.equals(buffer.inspect(), buffer2.inspect());
// do something useful with the buffers

Look at test.js for more examples and node-iconv's behaviour under error conditions.


Things to keep in mind when you work with node-iconv.

Chunked data

Say you are reading data in chunks from a HTTP stream. The logical input is a single document (the full POST request data) but the physical input will be spread over several buffers (the request chunks).

You must accumulate the small buffers into a single large buffer before performing the conversion. If you don't, you will get unexpected results with multi-byte and stateful character sets like UTF-8 and ISO-2022-JP.

node-buffertools lets you concatenate buffers painlessly. See the description of buffertools.concat() for details.

Dealing with untranslatable characters

Characters are not always translatable to another encoding. The UTF-8 string "ça va が", for example, cannot be represented in plain 7-bits ASCII without some loss of fidelity.

By default, node-iconv throws EILSEQ when untranslatabe characters are encountered but this can be customized. Quoting the iconv_open(3) man page:

    When  the  string  "//TRANSLIT"  is appended to tocode, transliteration is activated.
    This means that when a character cannot be represented in the target character set,
    it can be approximated through one or several similarly looking characters.

    When the string "//IGNORE" is appended to tocode, characters that cannot be represented
    in the target character set will be silently discarded.

Example usage:

var iconv = new Iconv('UTF-8', 'ASCII');
iconv.convert('ça va'); // throws EILSEQ

var iconv = new Iconv('UTF-8', 'ASCII//IGNORE');
iconv.convert('ça va'); // returns "a va"

var iconv = new Iconv('UTF-8', 'ASCII//TRANSLIT');
iconv.convert('ça va'); // "ca va"

var iconv = new Iconv('UTF-8', 'ASCII//TRANSLIT//IGNORE');
iconv.convert('ça va が'); // "ca va "


EINVAL is raised when the input ends in a partial character sequence. This is a feature, not a bug.

Something went wrong with that request. Please try again.