i18n Module (Internationalization)

This guide describes the i18n module of KIMU-Core: structure, available classes and services, and how to integrate it into extensions (e.g., kimu-home).

---

What is the i18n module?

The i18n module provides services and tools for interface localization and dynamic language management in the application.

Goals

• Manage the app's global language
• Load and provide localized translations
• Offer simple APIs to translate strings and change language at runtime

---

Module structure

src/
  modules/
    i18n/
      kimu-global-lang.ts      // Singleton for global language
      kimu-i18n-service.ts     // Main translation service
      helpers.ts               // Support functions (e.g., formatDate)
      resources/               // Translation files (e.g., it.json, en.json)
      module.ts                // Module entry point
      index.ts                 // Exports everything

---

Main classes and services

KimuGlobalLang

• Singleton that manages the application's global language
• API: getLang(), setLang(lang), onChange(callback)
• Notifies listeners when the language changes

KimuI18nService

• Main translation service
• API:
  • setLang(lang): changes language and loads translations
  • getLang(): returns the active language
  • translate(key, params?): translates a key, optionally interpolating parameters
  • onChange(callback): notifies when language or translations change

helpers.ts

• Utility functions to format dates, numbers, etc. according to the active language

---

How to use the i18n module

1. Load via Module Manager

const i18nModule = await app.moduleManager.loadModule('i18n');
const i18nService = i18nModule.getService();

2. Set the global language

i18nService.setLang('en');

3. Translate strings

const welcome = i18nService.translate('welcome');

4. React to language changes

i18nService.onChange(() => {
  // Update UI or reload localized data
});

---

Example: integration in an extension (kimu-home)

import { KimuI18nService } from '../../modules/i18n/kimu-i18n-service';

export class KimuHomeComponent extends KimuComponentElement {
  private i18nService: KimuI18nService;
  selectedLang = 'en';

  async onInit() {
    const i18nModule = await this.getApp().moduleManager.loadModule('i18n');
    this.i18nService = i18nModule.getService();
    await this.i18nService.setLang(this.selectedLang);
    this.i18nService.onChange(() => this.onRender());
  }

  getData() {
    return {
      // ...other data...
      translate: this.i18nService.translate,
    };
  }
}

---

Resources and translation files

• /src/modules/i18n/resources/it.json — Italian translations
• /src/modules/i18n/resources/en.json — English translations

Typical format:

{
  "welcome": "Welcome!",
  "logout": "Logout"
}

---

Best practices

• Always use the i18n service for all user-facing strings
• Bind the UI to language change events to update dynamically
• Keep translation resources organized by language
• Avoid hardcoding strings in the interface