@{test.blades.mytestblade.title}

# 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

```xml
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.

```xml
<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](../../../images/i18n-example-original.png)

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

```html
<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](../../../images/i18n-example-html.png)

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

**📌 NOTE**\
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**.

```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](../../../images/i18n-example-js.png)

## 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](../../../images/i18n-example-spanish.png)

## Useful Tips

### Missing Translations

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

![i18n-example-missing](../../../images/i18n-example-missing.png)

### 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: /&lt;appname>/app/aspect/&lt;aspectname>/resources/i18n
* BladeSet: /&lt;appname>/app/&lt;bladesetname>/bladeset/resources/i18n
* Blade: /&lt;appname>/app/bladeset/blade/&lt;bladesetname>/&lt;bladename>/resources/i18n