A pre-compiler for angular-translate based on TL: a simple write-less markup specially designed for angular-translate.
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');
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.
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']
}
}
}
});
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'
]);
});
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
}
}
},
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'
]);
Type: String
Default value: 'angTranslations'
Determines the name of the compiled variable. Ex: var angTranslations = {"usEn":{...}}
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.
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.
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.
Type: Boolean
Default value: false
Convert the output file to CoffeeScript.
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.
(Nothing yet)