Internationalising your app

In this tutorial we will go through a worked example of how to set up internationalisation for your App

Before starting this tutorial you should create a new app with a bladeset and a single blade

Set up Supported Locales

Have a look in $APP_ROOT/app.conf. It defines the locales that your app will support

appNamespace: <namespace>
locales: en, de, es

Include the Internationalisation Bundler

Include the Internationalisation Bundler in your app and workbench, by adding the i18n.bundle line into your index.html file.

<head>
<title>Workbench</title>

<@css.bundle theme="standard"@/>
<@i18n.bundle@/>
<@js.bundle@/>
</head>

Internationalising HTML

We will be using the workbench generated inside a newly created blade for this example. This is what it looks like before we make changes.

i18n example original

Let’s add a new element inside our HTML, which will be automatically internationalised. Internationalisation markup in BladeRunner takes the form of: @{<token>}. It’s best to namespace your token so that other blades don’t overwrite each other’s tokens

<div id="test.blades.mytestblade.view-template">
   <h1>@{test.blades.mytestblade.title}</h1>
   <div class="hello-world-message" data-bind="text:message"></div>
   <button class="button" data-bind="click:buttonClicked">Log me</button>
</div>

Then define the token translation inside the file: $BLADE_ROOT/resources/i18n/en/en.properties

test.blades.mytestbladetitle=Cool Title

Refresh the workbench, and it should look like this

i18n example html

The token replacement works by replacing all i18n tokens in all HTML as it is streamed through the HTML Bundler.

Things that are not loaded by the HTML Bundler do not have their tokens replaced. For example, the app’s index.html file, or anything in the unbundled-resources directory.

Internationalising JavaScript

Let’s add an internationalised Presenter property to the blade’s presentation model at $BLADE_ROOT/src/myapp/blades/myblade/ExampleClass.js.

test.blades.mytestbladeExampleClass = function()
{
    var sMessage = ct.i18n("test.blades.mytestblade.helloworldmessage" );
    this.message = new caplin.presenter.property.Property(sMessage);
    ...
}

Then add the translation to the i18n resource file.

test.blades.mytestblade.helloworldmessage=Internationalised Hello World!

After a sneaky refresh of the blade workbench, your token should have been replaced, and it should look like this:

i18n example js

Add a New Language

Create a file $BLADE_ROOT/resources/i18n/es/es.properties file, containing:

test.blades.mytestblade.title=Titulo Guay
test.blades.mytestblade.helloworldmessage=Hola Mundo Internacionalizado!

Loading the app with a Spanish locale set in the browser, will display like this:

i18n example spanish

Useful Tips

Missing Translations

If you miss out a translation, then the i18n makes it pretty obvious to you.

i18n example missing

I18n at Different Levels

You can internationalise at different levels of your application, by locating property files under the different levels in their resource folders

  • Aspect: /<appname>/app/aspect/<aspectname>/resources/i18n

  • BladeSet: /<appname>/app/<bladesetname>/bladeset/resources/i18n

  • Blade: /<appname>/app/bladeset/blade/<bladesetname>/<bladename>/resources/i18n