grunt-translate-compile
A pre-compiler for angular-translate based on TL: a simple write-less markup specially designed for angular-translate.
Getting Started
This plugin requires Grunt ~0.4.5
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-translate-compile --save-dev
Once the plugin has been installed, it may be enabled inside your Gruntfile with this line of JavaScript:
grunt.loadNpmTasks('grunt-translate-compile');
Translation Markup - TL
The translation markup intends to drastically reduce the amount of typing needed to translate your app, by keeping it simpler and improving it's maintenance. To learn more about the TL markup, please refer to the full documentation.
Briefing: A translation file begins with the declaration of all supported languages of your application. A custom numeric code (key) must be assigned to each one of the declared languages. In the sample that comes next, we're saying that [american english code is 1], [brazilian portuguese is 2] and [spanish from spain is 3]. Translation values are assigned directly to the language key.
Here goes a sample TL markup code:
LANGUAGES
1:enUs
2:ptBr
3:esEs
MENU
USER
LABEL
1:User
2:Usuário
3:Usuario
DROPDOWN
EDIT
1:Edit
2,3:Editar
LOGOUT
1:Logout
2:Sair
3:Finalizar la Sesión
CART
EMPTY
1:Empty Cart
2:Esvaziar Carrinho
3:Vaciar Carrito
CHECKOUT
1:Checkout
2:Fechar Pedido
3:Realizar Pedido
Compiling the above will result the bellow:
var angTranslations = {
"enUs": {
"MENU": {
"USER": {
"LABEL": "User",
"DROPDOWN": {
"EDIT": "Edit",
"LOGOUT": "Logout"
}
},
"CART": {
"EMPTY": "Empty Cart",
"CHECKOUT": "Checkout"
}
}
},
"ptBr": {
"MENU": {
"USER": {
"LABEL": "Usuário",
"DROPDOWN": {
"EDIT": "Editar",
"LOGOUT": "Sair"
}
},
"CART": {
"EMPTY": "Esvaziar Carrinho",
"CHECKOUT": "Fechar Pedido"
}
}
},
"esEs": {
"MENU": {
"USER": {
"LABEL": "Usuario",
"DROPDOWN": {
"EDIT": "Editar",
"LOGOUT": "Finalizar la Sesión"
}
},
"CART": {
"EMPTY": "Vaciar Carrito",
"CHECKOUT": "Realizar Pedido"
}
}
}
};
Notice how the writing was significantly reduced as it's no longer needed to rewrite every key for each language, we are also skipping blocks and quotes. Thus we can focus on what really matters, the translations. Maintenance is also greatly improved, as adding a new key will no longer be a hunt for the right spot of each language. Equal translations are also single written as multiple language keys may be assigned to a value (checkout 'user.dropdown.edit' key).
Please refer to the full documentation for more examples and capabilities.
The "translate_compile" task
Overview
1. Add the task
In your project's Gruntfile, add a section named translate_compile
to the data object passed into grunt.initConfig()
.
grunt.initConfig({
translate_compile: {
compile: {
options: {
// task-specific options go here. refer to options topic
},
files: {
// post-compiling file to the left, pre-compiling files to the right
'compiled-translations.js': ['translations/*.tl']
}
}
}
});
2. Let your server know about it
Remember to include "translate_compile" inside your server task so the compilation takes place when you start it (connect/express). Something like:
grunt.registerTask('serve', function (target) {
grunt.task.run([
'clean:server',
'translate_compile:compile', // <-- here it is
'bowerInstall',
'concurrent:server',
'autoprefixer',
'connect:livereload',
'watch'
]);
});
3. Watch it
For a better experience, watch for any changes made to your translation files (requires grunt-contrib-watch). Something like:
watch: {
tl: {
files: ['translations/*.tl'],
tasks: ['translate_compile:compile'],
options: {
livereload: true
}
}
},
4. Take it to your build
Add the "translate_compile" to your build task. Something like:
grunt.registerTask('build', [
'clean:dist'
'bowerInstall',
'useminPrepare',
'concurrent:dist',
'autoprefixer',
'concat',
'ngmin',
'translate_compile:compile', // <-- here it is
'copy:dist',
'cdnify',
'cssmin',
'uglify',
'rev',
'usemin',
'htmlmin'
]);
You should now be good to go!
Options
options.translationVar
Type: String
Default value: 'angTranslations'
Determines the name of the compiled variable. Ex: var angTranslations = {"usEn":{...}}
options.multipleObjects
Type: Boolean
Default value: false
If multipleObjects
is set to true
there will no longer be only one root variable like angTranslations
. Translations will now be splitted into one object per language. Ex: var enUs = {...}; var ptBr = {...}; var esEs = {...};
Variable names will the ones declared in the LANGUAGES
section.
options.asJson
Type: Boolean
Default value: false
Should this value be set to true there will be no variable assignment inside the file, only the resulting json will be there.
options.filePerLang
Type: Boolean
Default value: false
If this values is set to true
the translations will be split into separate files for each language.
Place {lang}
in the destination file name when using this option:
files: {
'compiled_translation_{lang}.json': ['translations/*.tl']
}
{lang}
will be replaced by the corresponding language id for the file. For example if you have translations with language keys
"en-Us"
and "pt-Br"
and the above file template, the following files will be generated:
compiled_translation_en-Us.json
compiled_translation_pt-Br.json
options.moduleExports
Type: Boolean
Default value: false
Use with options.asJson
for generate a Nodejs module or options.multipleObjects
to generate a file divided in different modules per language.
options.coffee
Type: Boolean
Default value: false
Convert the output file to CoffeeScript.
Contributing
In lieu of a formal styleguide, take care to maintain the existing coding style. Add unit tests for any new or changed functionality. Lint and test your code using Grunt.
Release History
(Nothing yet)