AkiLocale

A localization library for Akinon applications. Wraps i18next with a simplified API for managing translations.

Installation

pnpm add @akinon/akilocale

Basic Usage

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

// Create a locale instance with translations
const locale = Akilocale.createInstance({
  fallbackLng: 'en',
  translations: {
    en: {
      greeting: 'Hello',
      welcome: 'Welcome, {{name}}!'
    },
    tr: {
      greeting: 'Merhaba',
      welcome: 'Hoş geldin, {{name}}!'
    }
  }
});

// Use the translation function
locale.t('greeting'); // "Hello" or "Merhaba" based on current language
locale.t('welcome', { name: 'John' }); // "Welcome, John!"

// Get current language
console.log(locale.lng); // "en"

API Reference

Akilocale.createInstance

Creates a new locale instance with the provided translations.

const locale = Akilocale.createInstance({
  debug: false,
  fallbackLng: 'en',
  initialLanguage: 'tr',
  translations: {
    en: enTranslations,
    tr: trTranslations
  }
});

Options

Option	Type	Default	Description
translations	Record<string, Translations>	-	Translation objects keyed by language code
fallbackLng	string	'en'	Fallback language when translation is missing
initialLanguage	string	undefined	Initial language (overrides localStorage)
debug	boolean	false	Enable debug logging

Returns: AkilocaleInstance

Property	Type	Description
t	(key: string, options?: TOptions) => string	Translation function
lng	string	Current language code

---

Akilocale.setLanguage

Persists the selected language to localStorage. Requires page reload to take effect.

Akilocale.setLanguage('tr');

Parameters

Parameter	Type	Description
lng	string	Language code to set

---

Translation Function (t)

The t function translates keys with optional interpolation.

const { t } = Akilocale.createInstance({ ... });

// Simple translation
t('greeting'); // "Hello"

// With interpolation
t('welcome', { name: 'John' }); // "Welcome, John!"

// Nested keys
t('nested.part1'); // Access nested translations

// Dot notation in keys
t('hello.world'); // Keys can contain dots

---

Translation Structure

Translations can be flat or nested objects:

const translations = {
  en: {
    // Flat keys
    greeting: 'Hello',
    farewell: 'Goodbye',
    
    // Interpolation with {{variable}}
    welcome: 'Welcome, {{name}}!',
    items: 'You have {{count}} items',
    
    // Dot notation keys (not nested)
    'button.submit': 'Submit',
    'button.cancel': 'Cancel',
    
    // Nested structure
    errors: {
      required: 'This field is required',
      minLength: 'Minimum {{min}} characters'
    }
  }
};

React Integration

For React applications, use the /react export which provides react-i18next integration:

import { i18n, Trans, useTranslation } from '@akinon/akilocale/react';

const MyComponent = () => {
  const { t } = useTranslation();
  
  return (
    <div>
      <h1>{t('title')}</h1>
      <Trans i18nKey="description">
        Welcome to <strong>our app</strong>
      </Trans>
    </div>
  );
};

---

Language Persistence

Akilocale automatically persists language selection to localStorage:

// Storage key used: 'locale'
import { AKILOCALE_STORAGE_KEY } from '@akinon/akilocale';

// Set language (persists to localStorage)
Akilocale.setLanguage('tr');

// On next createInstance call, language is read from localStorage
const locale = Akilocale.createInstance({
  fallbackLng: 'en',
  translations
});

console.log(locale.lng); // 'tr' (from localStorage)

Language Priority

1. initialLanguage option (if provided)

2. localStorage value (if exists)

3. fallbackLng option

---

Common Use Cases

App Initialization

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

import en from './locales/en.json';
import tr from './locales/tr.json';

// Create global locale instance
export const locale = Akilocale.createInstance({
  fallbackLng: 'en',
  translations: { en, tr }
});

// Export for use throughout the app
export const { t } = locale;

Language Switcher

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

const LanguageSwitcher = () => {
  const handleLanguageChange = (lng: string) => {
    Akilocale.setLanguage(lng);
    window.location.reload(); // Reload to apply new language
  };

  return (
    <div>
      <button onClick={() => handleLanguageChange('en')}>English</button>
      <button onClick={() => handleLanguageChange('tr')}>Türkçe</button>
    </div>
  );
};

Integration with Akidate

Keep Akidate in sync with Akilocale for consistent date formatting:

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

import en from './locales/en.json';
import tr from './locales/tr.json';

const locale = Akilocale.createInstance({
  fallbackLng: 'en',
  translations: { en, tr }
});

// Sync Akidate with current language
akidate.setLocale(locale.lng);

export const { t } = locale;

With Intl APIs

Use locale.lng for native JavaScript internationalization:

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

const locale = Akilocale.createInstance({ ... });

// Currency formatting
const formatPrice = (value: number) => {
  return new Intl.NumberFormat(locale.lng, {
    style: 'currency',
    currency: 'USD'
  }).format(value);
};

// Date formatting (prefer Akidate for consistency)
const formatDate = (date: Date) => {
  return new Intl.DateTimeFormat(locale.lng, {
    dateStyle: 'long'
  }).format(date);
};

// Number formatting
const formatNumber = (value: number) => {
  return new Intl.NumberFormat(locale.lng).format(value);
};

Table with Translations

import type { AkitableColumn } from '@akinon/akitable';

import { t } from './locale';

const columns: AkitableColumn<Product>[] = [
  {
    title: t('table.name'),
    dataIndex: 'name'
  },
  {
    title: t('table.status'),
    dataIndex: 'status',
    render: (status) => t(`status.${status}`)
  }
];

---

Translation File Organization

JSON Files (Recommended)

// locales/en.json
{
  "common": {
    "save": "Save",
    "cancel": "Cancel",
    "delete": "Delete"
  },
  "errors": {
    "required": "This field is required",
    "invalid": "Invalid value"
  }
}

TypeScript Files

// locales/en.ts
export default {
  common: {
    save: 'Save',
    cancel: 'Cancel'
  }
} as const;

---

Best Practices

1. Create a single instance - Initialize locale once at app startup and export t

2. Use JSON files - Store translations in JSON for easy editing and tooling support

3. Consistent key naming - Use dot notation or nested structure, but be consistent

4. Sync with Akidate - Call akidate.setLocale(locale.lng) after initialization

5. Handle missing translations - Missing keys return the key itself, useful for development

6. Reload on language change - Call window.location.reload() after setLanguage for full effect

Related

• Akidate - Date formatting with locale support