@akinon/akilocale

AkiLocale

Akii18n provides a way to internationalize Akinon products. Its main purpose is to provide a way to translate the texts in the application to different languages.

Features

• It's framework agnostic so it can be used in any project.
• Multiple instances can be created to lazy load translations.
• It provides a way to set the language globally so all Akinon products can pick up the language.

Installation

npm install @akinon/akii18n

Usage

We need to create a new instance of akii18n and provide the translations to it. After creating the instance, we can use the t method to get the translation of a key.

import { akii18n } from '@akinon/akii18n';

export const i18n = akii18n.createInstance({
  debug: true,
  fallbackLng: 'en',
  translations: {
    en: {
      hello: 'Hello',
      inter: 'Hello {{val}}',
      'hello.world': 'Hello World',
      nested: {
        part1: 'Nested part1'
      }
    },
    tr: {
      hello: 'Merhaba',
      inter: 'Merhaba {{val}}',
      'hello.world': 'Merhaba Dünya',
      nested: {
        part1: 'Yerleşik parça1'
      }
    }
  }
});

console.log(i18n.t('hello')); // Hello
console.log(i18n.t('inter', { val: 'World' })); // Hello World
console.log(i18n.t('hello.world')); // Hello World
console.log(i18n.t('nested.part1')); // Nested part1
console.log('hello', { lng: 'tr' }); // Merhaba

Translation files

It's a good idea to keep translations in separate files.

• The keys in the translation files can be deeply nested or flat strings with dots.
• Translation files can be in js, ts, or json format.

// translations/en.ts
export default {
  hello: 'Hello'
  "hello.world": 'Hello World',
  nested: {
    part1: 'Nested part1'
  }
};

// translations/tr.ts
export default {
  hello: 'Merhaba',
  'hello.world': 'Merhaba Dünya',
  nested: {
    part1: 'Yerleşik parça1'
  }
};

import { akii18n } from '@akinon/akii18n';

import en_filter from './translations/en';
import tr_filter from './translations/tr';

export const i18n = akii18n.createInstance({
  debug: true,
  fallbackLng: 'en',
  translations: {
    en: en_filter,
    tr: tr_filter
  }
});

Interpolation

We can use the {{key}} syntax to interpolate values in the translations.

export const i18n = akii18n.createInstance({
  translations: {
    en: {
      myName: 'My name is {{name}}'
    },
    tr: {
      myName: 'Benim adım {{name}}'
    }
  }
});

console.log(i18n.t('myName', { name: 'John' })); // My name is John

Setting the language

Before creating the instance, we can set the language with the setLanguage method. This will set a global reference in localStorage and all the instances will use this language.

If you set the language after creating the instance, it will not affect the already created instances so you may need to reload your application to see the changes.

The reason we don't provide a way to pass the language to the instance is that we want to keep the instances stateless for the language selection. This way, we sync multiple instances with the same language.

import { akii18n } from '@akinon/akii18n';

aki18n.setLanguage('tr');

export const i18n = akii18n.createInstance({
  debug: true,
  fallbackLng: 'en',
  translations
});

import ts from 'typescript';

Lazy loading strategy

If you have a large number of translations, it's a good idea to lazy load them. You can create multiple instances and load the translations when needed.

For example, you can create a new instance for each page which will only load the translations for only that page. This way, you can reduce the initial load time of your application.