angular-gettext - gettext utilities for angular.js
Translate your Angular.JS applications with gettext.
Getting started
Add angular-gettext to your project:
-
Grab the files, either by copying the files from the dist
folder or (preferably) through bower: bower install --save angular-gettext
.
-
Include the angular-gettext source files in your app:
<script src="bower_components/angular-gettext/dist/angular-gettext.min.js"></script>
-
Add a dependency to angular-gettext in your Angular app:
angular.module('myApp', ['gettext']);
You can now start using the translate
directive to mark strings as translatable.
Next steps:
- Annotate strings with the
translate
directive. - Extract strings from the source code.
- Translate strings
- Integrate translated strings back into the application.
- Set the correct language for translations.
Using the translate
directive
Strings are marked as translatable using the translate
directive. Here's a simple example:
<h1 translate>Hello!</h1>
This div will automatically be translated using the translated strings (which we'll define later on). For instance, in Dutch, it might read Hallo!
.
Plurals
Plural strings can be annotated using two extra attributes: translate-n
and translate-plural
:
<div translate translate-n="count" translate-plural="{{count}} boats">One boat</div>
The general format is:
<div translate translate-n="COUNTEXPR" translate-plural="PLURALSTR">SINGULARSTR</div>
Depending on the value of COUNTEXPR
, either the singular string or the plural string will be selected.
Interpolation
Full interpolation support is available in translated strings, so the following will work as expected:
<div translate>Hello {{name}}!</div>
Using the translate
filter
There's also a filter available. This filter does not support plural strings:
<input type="text" placeholder="{{'Username'|translate}}" />
Use grunt-angular-gettext
to extract strings from your HTML templates into a .pot
catalog.
Translate strings
Use a tool like poedit, Pootle or Transifex to translate the strings.
Setting translated strings
You can set translated strings by injecting the gettextCatalog
and using the setStrings
method.
As an example, you may have the following code in your application:
angular.module('myApp').run(function (gettextCatalog) {
gettextCatalog.setStrings('nl', {
'Hello': 'Hallo',
'One boat': ['Een boot', '{{count}} boats']
});
});
Converting translated .po
files into angular-compatible JavaScript files can be done automatically using the grunt-angular-gettext
module.
Setting the language
Set the language by setting a language code on the catalog:
angular.module('myApp').run(function (gettextCatalog) {
gettextCatalog.currentLanguage = 'nl';
});
You can do this anywhere in your application, the use of a run
block above is just an example.
Highlighting untranslated strings
You can enable a debugging mode to clearly indicate untranslated strings:
angular.module('myApp').run(function (gettextCatalog) {
gettextCatalog.debug = true;
});
This will prepend `[MISSING]:` to each untranslated string.
## Contributing
All code lives in the `src` folder and is written in CoffeeScript. Try to stick to the style conventions used in existing code.
Tests can be run using `grunt test`. A convenience command to automatically run the tests is also available: `grunt watch`. Please add test cases when adding new functionality: this will prove that it works and ensure that it will keep working in the future.
## License
(The MIT License)
Copyright (C) 2013 by Ruben Vermeersch <ruben@savanne.be>
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.