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.

1{
2  "en" : "This is a color",
3  "en-GB" : "This is a colour",
4  "fr" : "Ceci est une couleur"
5} 

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:

1npm install grunt-po2json-embed --save-dev

Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:

1grunt.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().

1grunt.initConfig({
2  po2jsonEmbed: {
3    options: {
4      functionName: "tr",
5      poFiles: "translations",
6      defaultLanguage: "en"
7    },
8    target: {
9      files: {
10        js : [builddir+'/**/*.html', builddir+'/**/*.js']
11    }
12  },
13})

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") - GOOD

Usage Examples

Real-world example

1module.exports = function(grunt) {
2
3    var _ = grunt.util._;
4    var locales = ["fr"];
5    var prodir = 'debug';
6    var builddir = 'build/'+prodir;
7
8    grunt.initConfig({
9        pkg: grunt.file.readJSON('package.json'),
10    
11        watch : {
12            compass: {
13                files: ['compile/css/*.scss'],
14                tasks: ['compass:build']
15            },
16            js: {
17                files: ['compile/js/*.js'],
18                tasks: ['copy:js']
19            },
20            copy: {
21                files: ['copy/**/*'],
22                tasks: ['copy:base']
23            },
24            translations: {
25                files: [builddir+'/*.html', 'build/**/*.js'],
26                tasks: ['xgettext', 'shell']
27            },
28            transplant: {
29                files: ['translations/*.po'],
30                tasks: ['po2jsonEmbed']
31            },
32
33        },
34
35      clean: {
36            build: {
37                src: [builddir]
38            }
39      },
40
41        compass: {
42            build: {
43                options: {              
44                    config: 'compass-'+prodir+'.rb'
45                }
46            }
47        },
48
49      connect: {
50         server: {
51                options: {
52                    port: 4000,
53                    base: builddir+'/',
54                    hostname: '*'
55                }
56            }
57      },
58        
59        copy: {
60            base: {
61                files: [
62                    {
63                        expand: true,
64                        cwd: 'copy', src: ['**'],
65                        dest: builddir+'/'
66                    }
67                ]
68            },
69
70            js: {
71                files: [
72                    {
73                        expand: true,
74                        cwd: 'compile/js', src: ['**'],
75                        dest: builddir+'/cdn/js'
76                    }
77                ]
78            }
79        },
80
81      xgettext: {
82          target: {
83                files: {
84                    html: [builddir+'/**/*.html', builddir+'/**/*.js']
85                },
86                options: {
87                    functionName: '_tr',
88                    potFile: 'translations/messages.pot'
89                }
90          }
91      },
92
93        po2jsonEmbed: {
94            target: {
95                files : {
96                    js : [builddir+'/**/*.html', builddir+'/**/*.js']
97                },
98                options: {
99                    functionName: '_tr',
100                    poFiles: 'translations',
101                }
102            }
103        },
104
105      shell: {
106          options: {
107            failOnError: true
108          },
109          msgmerge: {
110            // todo: dynamic po file list would be better
111            command: _.map(locales, function(locale) {
112            var po = "translations/" + locale + ".po";
113            return "if [ -f \"" + po + "\" ]; then\n" +
114                   "    echo \"Updating " + po + "\"\n" +
115                   "    msgmerge " + po + " translations/messages.pot > .new.po.tmp\n" +
116                   "    exitCode=$?\n" +
117                   "    if [ $exitCode -ne 0 ]; then\n" +
118                   "        echo \"Msgmerge failed with exit code $?\"\n" +
119                   "        exit $exitCode\n" +
120                   "    fi\n" +
121                   "    mv .new.po.tmp " + po + "\n" +
122                   "fi\n";
123            }).join("")
124          }
125      }
126
127    });
128    
129    grunt.loadNpmTasks('grunt-contrib-watch');
130    grunt.loadNpmTasks('grunt-contrib-compass');
131    grunt.loadNpmTasks('grunt-contrib-copy');
132    grunt.loadNpmTasks('grunt-contrib-clean');
133    grunt.loadNpmTasks('grunt-xgettext');
134    grunt.loadNpmTasks('grunt-po2json-embed');
135    grunt.loadNpmTasks('grunt-contrib-connect');
136    grunt.loadNpmTasks('grunt-shell');
137
138    grunt.registerTask('build', ['clean:build', 'copy:base', 'copy:js', 'compass:build','xgettext','shell','po2jsonEmbed']);
139
140    grunt.registerTask('default', ['build','connect','watch']);
141};
142

Release History

0.1

• Initial release. Implemented for Igaro App SPA JS Framework.