About
The localisation module allows you to translate content on client side. This is especially useful if the used (CMS) system is not able to translate the content server side or if no hard reload should happen if the language was changed.
Install
npm install --save @ribajs/i18n
Regist
To regist the module import import i18nModule from '@ribajs/i18n'; and any LocalesService in your main.ts file and regist the module with riba.module.regist(i18nModule(localesService));:
import { coreModule, Riba } from '@ribajs/core';
import { ready } from '@ribajs/utils/src/dom';
import { LocalesService } from '@ribajs/shopify-tda';
import i18nModule from '@ribajs/i18n';
const riba = new Riba();
const localesService = new LocalesService();
const model = {};
riba.module.regist(coreModule);
riba.module.regist(i18nModule(localesService));
ready(() => {
riba.bind(document.body, model);
});
Templates
The module recognizes the default language code using the lang attribute of the html element, so this attribute is required for the installation:
<!doctype html>
<html lang="en">
<head>
...
</head>
<body>
...
</body>
</html>
Events
To subscribe events from the i18n module create a new instance of the EventDispatcher with 'i18n' as his namespace:
import { EventDispatcher } from '@ribajs/core';
const event = new EventDispatcher('i18n');
event.on('changed', () => {
console.debug('The language was changed');
});
event.on('ready', () => {
console.debug('All locales are loaded and initialized and the module is ready to use');
});
| Name | Arguments | Description |
|---|---|---|
| changed | langcode, initial |
The language was changed |
| ready | currentLangcode, translationNeeded |
All locales are loaded and initialized and the module is ready to use. |
Services
ALocalesService
The ALocalesService is a abstract class extended from all locales services, a static LocalesService could look like this:
import { ALocalesService } from '@ribajs/i18n';
export class MyStaticLocalesService extends ALocalesService {
public static instances: {
[id: string]: MyStaticLocalesService;
} = {};
public static getInstance(id: string = 'main') {
return MyStaticLocalesService.instances[id];
}
/**
* The current setted langcode
*/
protected currentLangcode?: string;
/**
* The default theme langcode before any language was choosed
*/
protected initalLangcode?: string;
constructor(staticLocales: any, protected id?: string, doNotTranslateDefaultLanguage: boolean = false, showMissingTranslation: boolean = false) {
super(doNotTranslateDefaultLanguage, showMissingTranslation);
if (!id) {
id = 'main';
}
// Sets the static translations
this.locales = staticLocales;
// Return the singleton if available
if (MyStaticLocalesService.instances[id]) {
return MyStaticLocalesService.instances[id];
}
this.init();
MyStaticLocalesService.instances[id] = this;
}
/**
* Get object with all translations
* @param themeID
*/
protected async getAll(themeID?: number) {
return this.locales;
}
}
LocalesStaticService
The LocalesStaticService can be used to integrate and define the translations directly in the source code:
import { LocalesStaticService } from '@ribajs/i18n';
// Your static locales
const locales = {
de: {
examples: {
newsletter: {
description_html: 'Abonnieren Sie unseren Newsletter und erhalten Sie <strong>10% Rabatt</strong> auf Ihren nächsten Einkauf.',
input_value: 'Unbekannt',
placeholder_last_name: 'Nachname',
title: 'Melde dich für den Newsletter an',
},
},
},
en: {
examples: {
newsletter: {
description_html: 'Subscribe to our newsletter and get <strong>10% off</strong> your next purchase.',
input_value: 'Unknown',
placeholder_last_name: 'Surname',
title: 'Sign up for the newsletter',
},
},
},
};
const localesService = new LocalesStaticService(locales);
import { coreModule, Riba } from "@ribajs/core";
import { ready } from "@ribajs/utils/src/dom";
import { i18nModule, LocalesStaticService } from "@ribajs/i18n";
import I18nStaticModule from "./i18n-static.module";
const locales = {
de: {
examples: {
i18n: {
switch_language: "Klicke auf eine Sprache um sie zu ändern",
},
newsletter: {
description_html:
"Abonnieren Sie unseren Newsletter und erhalten Sie <strong>10% Rabatt</strong> auf Ihren nächsten Einkauf.",
input_value: "Unbekannt",
placeholder_last_name: "Nachname",
title: "Melde dich für den Newsletter an",
},
},
},
en: {
examples: {
i18n: {
switch_language: "Click on a language to change it",
},
newsletter: {
description_html:
"Subscribe to our newsletter and get <strong>10% off</strong> your next purchase.",
input_value: "Unknown",
placeholder_last_name: "Surname",
title: "Sign up for the newsletter",
},
},
},
};
const riba = new Riba();
const localesService = new LocalesStaticService(locales);
const model = {};
riba.module.regist(coreModule);
riba.module.regist(i18nModule(localesService));
riba.module.regist(I18nStaticModule);
ready(() => {
riba.bind(document.body, model);
});
<i18n-switcher>
<p><strong rv-i18n-text="'examples.i18n.switch_language'"></strong></p>
<div class="btn-group" role="group">
<button
type="button"
class="btn btn-secondary text-uppercase"
rv-each-langcode="langcodes"
rv-text="langcode.code"
rv-on-click="switch | args langcode"
rv-class-active="langcode.active"
>Left</button>
</div>
</i18n-switcher>
<div class="form-row my-5">
<div class="col-12">
<h1 rv-i18n-text="'examples.newsletter.title'"></h1>
<p rv-i18n-html="'examples.newsletter.description_html'"></p>
</div>
<div class="col">
<input type="text" class="form-control" rv-i18n-value="'examples.newsletter.input_value'" />
</div>
<div class="col">
<input type="text" class="form-control" rv-i18n-placeholder="'examples.newsletter.placeholder_last_name'" />
</div>
</div>
import {
Component,
} from '@ribajs/core';
import template from './i18n-static-example.component.html';
export class I18nStaticExampleComponent extends Component {
public static tagName: string = 'rv-i18n-static-example';
protected autobind = true;
static get observedAttributes() {
return [];
}
protected scope = {};
constructor(element?: HTMLElement) {
super(element);
}
protected connectedCallback() {
super.connectedCallback();
this.init(I18nStaticExampleComponent.observedAttributes);
}
protected async init(observedAttributes: string[]) {
return super.init(observedAttributes)
.then((view) => {
return view;
});
}
protected requiredAttributes() {
return [];
}
protected template() {
return template;
}
}
LocalesRestService
The LocalesRestService can be used to get the translation json object with a REST API call:
import { LocalesRestService } from '@ribajs/i18n';
const url = 'https://localhost/api/locales'
const localesService = new LocalesRestService(url);
Binders
i18n-[type]
Gets the (current selected) translation of a keypath string from your locales object (over the TranslationService).
The translation is set as html, text or value depending on the passed type, available types are html, text and value.
If the type is not known, the translation is instead set as an attribute with the given name, a useful example for this could be the placeholder attribute.
i18n-text
i18n-html
i18n-value
i18n-[attributeName]
Components
i18n-switcher
Use this component to switch to another available language, this component does not have its own template, so you neet to set this as child elements of this component by yourself.
Types
export interface Langcode {
code: string;
active: boolean;
}
Template methods
| Name | Arguments | Description |
|---|---|---|
| switch | langcode: Langcode | Triggeres the toggle event |
| toggle | Toggle to another language (only useful for two supported languages) |
Template properties
| Name | Type | Description |
|---|---|---|
| langcodes | Langcode[] |
Array of founded langcodes from your locales object |
| ready | boolean |
Is true if the locales are initialized |