Skip to Content
UI KitUtilitiesAkilocale

Overview

Akilocale provides a way to internationalize your applications. Its main purpose is to provide a way to translate the texts in the application to different languages.

How It Works

The Akilocale module exports Akilocale object, providing a consistent interface for internationalization operations.

Syntax

import { Akilocale } from '@akinon/akilocale';

Usage Example

We need to import the Akilocale object and provide the translations to it. After creating the instance, we can use the t() method to get the translation of a key.

// .../i18n/index.ts
 
import { Akilocale } from '@akinon/akilocale';
 
export const i18n = Akilocale.createInstance({
  debug: false,
  fallbackLng: 'en',
  initialLanguage: 'en', // optional: set initial language
  translations: {
    en: {
      active: 'Active',
      passive: 'Passive',
      'current.language': 'Current Language',
      ...
    },
    tr: {
      active: 'Aktif',
      passive: 'Pasif',
      'current.language': 'Geçerli Dil',
      ...
    }
  }
});
// .../MyComponent.tsx
 
import { i18n } from './i18n';
 
const { t, lng } = i18n;
 
const MyComponent = () => {
  return (
    <div>
      <p>
        {t('current.language')}: {lng}
      </p>
    </div>
  );
};
 
export default MyComponent;

Translation files

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

Translation files can be in js, ts, or json format.

// .../translations/en.ts
 
export default {
  active: 'Active',
  passive: 'Passive',
  'current.language': 'Current Language',
  ...
};
// .../translations/tr.ts
 
export default {
  active: 'Aktif',
  passive: 'Pasif',
  'current.language': 'Geçerli Dil',
  ...
};
// .../index.ts
 
import { Akilocale } from '@akinon/akilocale';
 
import en from './translations/en';
import tr from './translations/tr';
 
export const i18n = Akilocale.createInstance({
  debug: false,
  fallbackLng: 'en',
  initialLanguage: 'tr', // optional: set initial language
  translations: {
    en,
    tr
  }
});

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 { Akilocale } from '@akinon/akilocale';
 
Akilocale.setLanguage('tr'); // set language to Turkish
 
import en from './translations/en';
import tr from './translations/tr';
 
export const i18n = Akilocale.createInstance({
  debug: false,
  fallbackLng: 'en',
  initialLanguage: 'en', // optional: set initial language (overrides setLanguage)
  translations: {
    en,
    tr
  }
});

Initial Language

You can also set the initial language directly when creating an instance using the initialLanguage parameter. This parameter takes priority over both the language stored in localStorage (set via setLanguage) and the fallback language.

The priority order for language selection is:

  1. initialLanguage (if provided)
  2. Language stored in localStorage (set via Akilocale.setLanguage())
  3. fallbackLng (default: ‘en’)
export const i18n = Akilocale.createInstance({
  debug: false,
  fallbackLng: 'en',
  initialLanguage: 'tr', // This will be used as the initial language
  translations: {
    en,
    tr
  }
});

Note: Unlike setLanguage(), the initialLanguage parameter only affects the specific instance being created and doesn’t modify localStorage or affect other instances.

Interpolation

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

export const i18n = Akilocale.createInstance({
  ...
  translations: {
    en: {
      myName: 'My name is {{name}}',
      ...
    },
    tr: {
      myName: 'Benim adım {{name}}',
      ...
    }
  }
});
console.log(t('myName', { name: 'John' })); // My name is John
Akidate