Cocorita language translation library
Install
npm install --save cocorita
Motivation
There are many great localization tools out there, if you need a fully customizable popular/standard solution then you should go for them.
If you just need translation then Cocorita can fit your needs, it's small and functional. Give it a try!
Migration from 1.x.x version
Starting from version 2.0.0 Cocorita adopted a fully ES6 module structure.
This implies you have to change your code only if you are using cocorita in a CommonJS module (with require) or in a browser.
No actions required if you are using cocorita in a ES6 module.
If you are using cocorita in a CommonJS module:
const Cocorita = require('cocorita');
const { Cocorita } = require('cocorita');
const Cocorita = require('cocorita').Cocorita;
If you are using cocorita in a browser you have to load the script from the "dist" folder.
The script expose the library with the global property "CocoLib". Here is an example:
<script type="text/javascript" src="<path to>/dist/cocorita.js"></script>
<script type="text/javascript">
const coco = new Cocorita(options);
const coco = new CocoLib.Cocorita(options);
</script>
Usage
API documentation is here.
Quick start (NodeJS)
const { Cocorita } = require('cocorita');
const coco = new Cocorita({ language: 'es' });
coco.load(fs.readFileSync('translations.yaml', { encoding: 'utf8' }), 'yaml'));
console.log( coco.tr('Hello Cocorita!') );
Quick start (Browser)
Example with database as a object in a script file:
database.js:
var translations = {
hello: {
en: 'hello',
es: 'hola',
it: 'ciao'
},
world: {
en: 'world',
es: 'mundo',
it: 'mondo'
}
}
html:
<script type="text/javascript" src="<path to>/dist/cocorita.js"></script>
<script type="text/javascript" src="database.js"></script>
<script type="text/javascript">
(function() {
var coco = new CocoLib.Cocorita({ language: 'es' });
coco.load(translations);
coco.tr('Hello Cocorita!');
}) ();
</script>
You could get the database in any other way. It could be a object, json or yaml:
<script type="text/javascript" src="cocorita.js"></script>
<script type="text/javascript">
(function() {
var coco = new CocoLib.Cocorita({ language: 'es' });
asyncLoadTranslations(function(err, data) {
if(err) {
else coco.load(data);
ready();
});
function ready() {
coco.tr('Hello Cocorita!');
}
}) ();
</script>
Options
Cocorita constructor will accept a options object with these keys:
{
language,
initialize
}
Replace in translated string
Sometimes you need to translate a text which contains some dynamic sections you want to set at run time.
In these cases, you can format your texts as a template (Cocorita support Mustache style tags) and use the replace object parameter:
coco.tr('You have {{ msglen }} new messages and {{ reqlen }} new requests!', {
msglen: messages.length,
reqlen: requests.length
});
translations database (YAML):
You have {{ msglen }} new messages and {{ reqlen }} new requests!:
it: Hai {{ msglen }} nuovi messaggi e {{ reqlen }} nuove richieste!
Database initialization
THIS FEATURE IS NOT INTENDED TO BE USED IN PRODUCTION ENVIRONMENT
Cocorita could initialize missing target translations for you.
To do so, you need to pass the 'initialize' languages array in the constructor options parameter:
const coco = new Cocorita({ initialize:['en', 'es', 'it', 'de'] });
then, any time the tr() function gets called, it will be checked if a translation is available for every of these languages. If a translation is missing, the source text will be added in place and a Cocorita.EVT_INIT_KEY event will be thrown.
You could listen for the event in order to update the database during development:
const coco = new Cocorita({ initialize:['en', 'es', 'it', 'de'] });
coco.on(Cocorita.EVT_INIT_KEY, (co, data, source, targets) => {
fs.writeFileSync('translations.yaml', co.dump('yaml'));
})
Error handling
Cocorita will throw errors if anyting unexpexted happen.
You should enclose error-throwing functions calls in try-catch blocks:
let coco;
try {
coco = new Cocorita();
coco.language = 'en';
coco.load(db);
} catch(e) {
}
coco.tr();
Data formats
Cocorita load function will accept a JavaScript object or a YAML or JSON strings with these formats:
JS Object:
{
hello: {
de: "hallo",
en: "hello",
es: "hola",
it: "ciao"
},
"hello\nworld": {
es: "hola\nmundo"
}
}
YAML:
hello:
de: hallo
en: hello
es: hola
it: ciao
"hello\nworld":
es: |-
hola
mundo
JSON:
{
"hello": {
"de": "hallo",
"en": "hello",
"es": "hola",
"it": "ciao"
},
"hello\nworld": {
"es": "hola\nmundo"
}
}
license
MIT License
Copyright (c) 2018 Valerio Bianchi
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.