bbl

Hyperlightweight Javascript Library for Localization, supporting both declarative and imperative modes.

Usage

Use bbl to dynamically load localization resources that contain phrase translations from a base language into a local one, and have those translations performed automatically on existing DOM elements, or programmatically via Javascript.

Setup

This library requires JQuery for the dynamic loading component (AJAX get). See the index.html for script includes. Only bbl.js is needed, it will load the language resources when needed.

Easiest way to see how everything works is to download the repo, drop it into your web server and have at it.

Using it in HTML

Use the data-bbl-html, data-bbl-text and data-bbl-value HTML tags to specify how the translation will be inserted into the DOM object whose visible content is being translated. FOr example, data-bbl-html would be used for divs and spans, text would be used for options in a select, and value would be used for buttons.

<span data-bbl-html="This is my content"></span>
<input type=button data-bbl-value="Translate" />
<select>
<option value="0" data-bbl-text="Your First Option"></option>
<option value="1" data-bbl-text="Your Second Option"></option>
</select>

Once your HTML is built, in Javascript you would set the bbl language resource:

<script>
  bbl.resource('js/trans_i10l_fr.js');
</script>

This will automatically convert the data-bbl-* elements to the translated values. innerHTML, values and texts of the various objects will be updated.

Note that setting the resource will actually append entries in that resource file to the existing dictionary being used by bbl. This lets you have a generic translation file, and then overlay that will additional content for an application-specific language file.

Use bbl.clear() to clear out the dictionary being used by bbl.

You can swap out the language file at any time by using bbl.clear() and bbl.resource(resourceFile).

You can also translate newly-added content by calling the following, which will translate all translatable elements in the DOM:

  bbl.all();

You can also translate a single object via:

  bbl.one(domElem);

Using it in Javascript

You can use bbl to programatically perform translations, either directly on DOM elements as described above, or simply assign translated values to a variable.

// change the resource
bbl.resource('js/trans_l10n_fr.js');
		
// translate something
var txt = bbl('one'); 
// outputs une

var txt = bbl('forty'); 
// outputs quarante
		
var txt = bbl('This is a story'); 
// outputs C'est une histoire

Language Resource Files

The resource files are straightforward JS objects configured as such:

bbl.set({
    'This is a sample': 'Ceci est un exemple',
    'This is sample {0} of {1}': 'C\'est échantillon {0} sur {1}',
    'one': 'une',
    'forty': 'quarante',
    'Usage': 'Utilisation',
    'bbl Localization Service': 'Service de localisation bbl',
    'change the resource': 'modifier la ressource',
    'translate something': 'traduire quelque chose',
    'outputs': 'sorties',
    'Language Resource': 'Ressource en Langues',
    'Use the {0} resource': 'Utilisez le {0} ressource',
    'Translate': 'Traduire',
    'Go ahead and change me':'Allez-y et changez-moi'
})

Each line is a base language phrase:translated language phrase.

Parameterization

bbl supports basic parameterization capabilities. This allows you to put variable terms within a translatable phrase, and in turn those variable terms can be translatable as well.

For example, you could have a base language phrase:

This is sample {0} of {1}

Where {0} and {1} represent the order of parameter values that will be provided in an Array (or in the data-bbl-parms HTML attribute, separated by bars | ).

In Javascript, you could translate the above via:

var trans = bbl('This is sample {0} of {1}',['1','40']);
// output will be C'est échantillon 1 sur 40

Because there are no translatable values for the two parameters, they will be simply dropped in as-is. Note that this is the case for any translation request -- if no translation of a phrase is available, the base phrase is returned.

If you do have translatable parameters, the parameters will be translated as well, i.e.

var trans = bbl('This is sample {0} of {1}',['one','forty']);
// output will be C'est échantillon une sur quarante

To do this declaratively in HTML, use data-bbl-parms:

<span data-bbl-html="This is sample {0} of {1}" data-bbl-parms="one|forty"></span>

Then, when the translation action occurs, the HTML will be replaced as above.