In addition to various view resources, which we'll see later in this chapter, the aurelia-i18n exports an I18N class, which acts as a facade over various APIs such as i18next and the native Intl API.

Let's see how we can use this API to get and set the current locale by creating a locale-picker custom element, which will allow the user to change the current locale:

src/resources/elements/locale-picker.html

<template> 
  <select class="navbar-btn form-control"  
          value.bind="selectedLocale"  
          disabled.bind="isChangingLocale"> 
    <option repeat.for="locale of locales" value.bind="locale"> 
      ${locale} 
    </option> 
  </select> 
</template> 

In this template, we start by adding a select element, whose value will be bound to the selectedLocale property, and which will be disabled when the isChangingLocale property is true. In the select element, we render one option for each value in the locales array. The value of each option is bound to its locale value, and the text of each option will be the locale itself, rendered using a string interpolation expression.

Next, we need to add the view-model, which will bridge this template with the I18N API:

src/resources/elements/locale-picker.js

import {inject, bindable} from 'aurelia-framework'; 
import {I18N} from 'aurelia-i18n'; 
 
@inject(I18N) 
export class LocalePickerCustomElement { 
  
  @bindable selectedLocale; 
  @bindable locales = ['en', 'fr']; 
 
  constructor(i18n) { 
    this.i18n = i18n; 
 
    this.selectedLocale = this.i18n.getLocale(); 
    this.isChangingLocale = false; 
  } 
 
  selectedLocaleChanged() { 
    this.isChangingLocale = true; 
    this.i18n.setLocale(this.selectedLocale).then(() => { 
      this.isChangingLocale = false; 
    }); 
  } 
} 

First, this class's constructor starts by receiving the I18N instance, then uses its getLocale method to retrieve the current locale and initialize the selectedLocale property. This property being bindable, the template declaring an instance can, however, data-bind to it to override its default value.

Next, the property change handler selectedLocaleChanged, which will be called by the templating engine when the selectedLocale property changes, sets the isChangingLocale to true so the select element is disabled, then calls the setLocale method of I18N. This method is asynchronous because it may have to load a new translation file from the server, so it returns a Promise, which we listen for completion to set isChangingLocale back to false, so the select element is re-enabled.

Since our locale picker supports English and French by default, we need to add another translation file for French, containing an empty object:

locales/fr/translation.json

{} 

We can now use this custom element in the app component:

src/app.html

<!-- Omitted snippet...--> 
<form class="navbar-search pull-right"> 
  <locale-picker></locale-picker> 
</form> 
<ul class="nav navbar-nav navbar-right"> 
  <!-- Omitted snippet...--> 
</ul> 
<!-- Omitted snippet...--> 

Of course, if you run the application at this point, nothing gets translated when you change the current locale; text translations must be added to the templates first.