version 0.1.5
icu-converter is a nodejs-based tool to convert ICU Resource Bundles into other formats.
- Sonar: http://hq.psikon.net:20010/dashboard/index?id=icu-converter
- Jenkins: http://hq.psikon.net:20020/jenkins/job/icu-converter/
- NPM: https://www.npmjs.com/package/icu-converter
genrb is the C-based tool ICU provides, which can compile ICU Resource Bundles into java properties, and a binary format. Unfortunately, it does not generate JSON, and at the time there was no Windows build of the tool. In the future, other formats will be supported as well.
The ICU Resource Bundle format is very tolerant and simple. But it's best feature, is cleanly handling new lines. Something many other formats have a hard time handling. It is much better geared towards non-programmers (such as your translators!).
For more information on this format, and best practices to resource bundle organization, visit the ICU Resources information at http://userguide.icu-project.org/locale/resources
If you wish to use the command line interpreter easily, install icu-converter globally:
npm install -g icu-converter
Remove the -g flag if you just want to use the library.
If you want bleeding edge code with no promises then clone the develop branch. You should also install the grunt-cli tool to run the build.
git clone https://github.com/alex-dow/icu-converter.git
cd icu-converter
git checkout develop
npm install
sudo npm install -g grunt-cli
grunt
icu-converter --help
Example usage:
$ icu-converter --format=json --output-dir=./output ./tests/fixtures/root.txt
> Processing: ./tests/fixtures/root.txt
$
This will generate a JSON file at ./output/root.json.
Valid values for format are:
jsonproperties
- Binary Data Type
- Imports
- Aliasing
From a file:
var parseFile = require('icu-converter').parseFile;
var jsObj = parseFile('/path/to/resourceBundle.txt', {
encoding: 'utf-8'
});
console.log(jsObj);From a string:
var parse = require('icu-converter').parse;
var resource = "root { msgid { "string" } }";
var jsObj = parse(resource);
console.log(jsObj);To convert a resource bundle to a different format, you must fetch a parser of the format you'd like to use:
var parseFile = require('icu-converter').parseFile;
var formatter = require('icu-converter').getFormatter('json');
var resourceFile = 'tests/fixtures/tables/table1.txt';
var jsObj = parseFile(resourceFile, {
encoding: 'utf-8'
});
var content = formatter.stringify(jsObj);Each parser has a method called stringify that takes a javascript object and converts it to a string.
The JSON Parser accepts only two options, which are used with JSON.stringify()
Type: string or int
Default: 0
A String or Number object that's used to insert white space into the output JSON string for readability purposes. If this is a Number, it indicates the number of space characters to use as white space; this number is capped at 10 if it's larger than that. Values less than 1 indicate that no space should be used. If this is a String, the string (or the first 10 characters of the string, if it's longer than that) is used as white space. If this parameter is not provided (or is null), no white space is used.
Type: function
Default: null
A function that alters the behavior of the stringification process, or an array of String and Number objects that serve as a whitelist for selecting the properties of the value object to be included in the JSON string. If this value is null or not provided, all properties of the object are included in the resulting JSON string.
The Properties parser will compile a Javascript object to the standard Java Properties format. Bare in mind that complex data structures are not easily representable in this format. As well, the standard Java properties library expects properties files to use the iso-8859-1 encoding. As such, unicode characters must be escaped.
The following options are available:
Type: boolean
Default: false
If enabled, then strings that have new lines in them will have their new lines escaped by \s\\\n instead of \\n.
With it enabled:
myProperty=string \
on \
many lines
With it disabled:
myProperty=string\non\nmany\nlines
Type: string
Default: \n
Specifcy which character or characters to use as the newline character.
Type: string
Default: '='
Specify which character or characters you wish to use to separate the key from the value
Type: boolean
Default: false
If enabled, then unicode characters will not be converted to \u[0000-ffff] escape sequences
root {
array {
{ "message" }
{ "message" }
{ "message" }
}
}
Will be turned into:
root.array.0=message
root.array.1=message
root.array.2=message
If an element in an array is another array or table however, then this will not be properly represented in Properties files. The current behavior is to export it as JSON.
root {
array {
{ "message" }
{ newTable {
field { "message" }
}}
}
}
Will be turned into
root.array.0=message
root.array.1={ newTable: { field: "message" } }
If a string element spans multiple lines, then it will also be split on multiple lines in the properties file, with each line ending in a \
root {
message { "multi
line
message" }
}
Will be turned into
root.message=multi \
line \
message
All of this behavior is hard coded for now. It's planned to allow more functionality when handling data structures that property files do not handle.
If you want to submit changes to the PEG file itself, then there must be extensive unit tests done to ensure that it works. Create fixtures for numerous examples and place in tests/fixtures and create tests for them.
Please respect the .editorconfig, .jshintrc, and .jscsrc files.
- 2015-12-10 v0.1.5 Removed a left over console.log() call in the PegJS file
- 2015-12-07 v0.1.4 Fix issue #27 - Using ints as key names
- 2015-12-04 v0.1.2 Support for escape characters - issue #25
- 2015-11-10 v0.1.1 Fix issue #22
- 2015-06-11 v0.1.0 Completely different architecture, bug fixes, support for integer data types, better support for type coersion
- 2015-06-06 v0.0.5 Bug fixes, better array handling, and starting the unit tests
- 2015-06-05 v0.0.4 Bug fixes and improved architecture
- 2015-06-04 v0.0.3 Added preliminary properties file converter, and other bug fixes
- 2015-06-04 v0.0.2 Fixed an issue with JSON converter, where string resources were stored in an needed nested object
- 2015-06-03 v0.0.1 Initial release