grunt-po2json-embed v1.0.0
grunt-po2json-embed
A Grunt plugin to convert PO translation files into JSON objects which are then embedded into the original files.
Introduction
Translations are wrapped in a function which is recognised by a parser, which generates a list of strings into a POT file. From this one generates language support by way of PO files. This project takes these PO files, scans the original files and embeds language as a JSON object.
The name of your PO files are used for the JSON object keys. It is highly recommended you use IETF tags for the file names (i.e en-GB, fr).
Most likely your original strings will be in English, so you wont generate an 'en' PO file. By default an en key will be added to the JSON, but you can change this in the options.
Theory
Files contain i18n("The color is red"). Another plugin such as grunt-xgettext scans these files and generates a POT file. You use poedit to create your language support by way of fr.po and en-GB.po.
This plugin takes the fr, en-GB file(s) and makes a structure.
{
"en" : "This is a color",
"en-GB" : "This is a colour",
"fr" : "Ceci est une couleur"
} It then replaces i18n("The color is red") with this structure, which is used with logic. Normally you'd write a function which knows the user language (i.e en-GB), attempts to match the key and if no match is found tries the denominator and then the default (in this case, en).
If you need such a function, see mapkey in core.language.js, found in the Igaro App project on github.
Given the files are replaced, you'll want to copy your source files into a build folder. You probably do this anyway by way of a js minify script.
Getting Started
If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:
npm install grunt-po2json-embed --save-devOnce the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
grunt.loadNpmTasks('grunt-po2json-embed');The "po2jsonEmbed" task
Overview
In your project's Gruntfile, add a section named po2jsonEmbed to the data object passed into
grunt.initConfig().
grunt.initConfig({
po2jsonEmbed: {
options: {
functionName: "tr",
poFiles: "translations",
defaultLanguage: "en"
},
target: {
files: {
js : [builddir+'/**/*.html', builddir+'/**/*.js']
}
},
})Options
options.functionName
Type: String
Default value: "tr"
The function name that marks translatable messages. Usually tr or i18n.
options.poFiles
Type: String
Default value: ""
The directory containing your .po files
options.defaultLanguage
Type: String
Default value: en
Files
Assuming the default functionName is used, translatable messages look like this:
tr("Some translatable message")Note: pluralisation is not supported. Instead use two strings and use Javascript to do the logic.
tr("You have %1 follower" "You have %1 followers" numFollowers) - WRONG
tr("You have %1 follower"), tr("You have %1 followers") - GOODUsage Examples
Real-world example
module.exports = function(grunt) {
var _ = grunt.util._;
var locales = ["fr"];
var prodir = 'debug';
var builddir = 'build/'+prodir;
grunt.initConfig({
pkg: grunt.file.readJSON('package.json'),
watch : {
compass: {
files: ['compile/css/*.scss'],
tasks: ['compass:build']
},
js: {
files: ['compile/js/*.js'],
tasks: ['copy:js']
},
copy: {
files: ['copy/**/*'],
tasks: ['copy:base']
},
translations: {
files: [builddir+'/*.html', 'build/**/*.js'],
tasks: ['xgettext', 'shell']
},
transplant: {
files: ['translations/*.po'],
tasks: ['po2jsonEmbed']
},
},
clean: {
build: {
src: [builddir]
}
},
compass: {
build: {
options: {
config: 'compass-'+prodir+'.rb'
}
}
},
connect: {
server: {
options: {
port: 4000,
base: builddir+'/',
hostname: '*'
}
}
},
copy: {
base: {
files: [
{
expand: true,
cwd: 'copy', src: ['**'],
dest: builddir+'/'
}
]
},
js: {
files: [
{
expand: true,
cwd: 'compile/js', src: ['**'],
dest: builddir+'/cdn/js'
}
]
}
},
xgettext: {
target: {
files: {
html: [builddir+'/**/*.html', builddir+'/**/*.js']
},
options: {
functionName: '_tr',
potFile: 'translations/messages.pot'
}
}
},
po2jsonEmbed: {
target: {
files : {
js : [builddir+'/**/*.html', builddir+'/**/*.js']
},
options: {
functionName: '_tr',
poFiles: 'translations',
}
}
},
shell: {
options: {
failOnError: true
},
msgmerge: {
// todo: dynamic po file list would be better
command: _.map(locales, function(locale) {
var po = "translations/" + locale + ".po";
return "if [ -f \"" + po + "\" ]; then\n" +
" echo \"Updating " + po + "\"\n" +
" msgmerge " + po + " translations/messages.pot > .new.po.tmp\n" +
" exitCode=$?\n" +
" if [ $exitCode -ne 0 ]; then\n" +
" echo \"Msgmerge failed with exit code $?\"\n" +
" exit $exitCode\n" +
" fi\n" +
" mv .new.po.tmp " + po + "\n" +
"fi\n";
}).join("")
}
}
});
grunt.loadNpmTasks('grunt-contrib-watch');
grunt.loadNpmTasks('grunt-contrib-compass');
grunt.loadNpmTasks('grunt-contrib-copy');
grunt.loadNpmTasks('grunt-contrib-clean');
grunt.loadNpmTasks('grunt-xgettext');
grunt.loadNpmTasks('grunt-po2json-embed');
grunt.loadNpmTasks('grunt-contrib-connect');
grunt.loadNpmTasks('grunt-shell');
grunt.registerTask('build', ['clean:build', 'copy:base', 'copy:js', 'compass:build','xgettext','shell','po2jsonEmbed']);
grunt.registerTask('default', ['build','connect','watch']);
};Release History
0.1
- Initial release. Implemented for Igaro App SPA JS Framework.