Localisation Module Reference

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, Utils } from '@ribajs/core';
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));
Utils.domIsReady(() => {
  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);

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