Modulo i18n (Internazionalizzazione)

Questa guida descrive il modulo i18n di KIMU-Core: struttura, classi, servizi disponibili e come integrarlo nelle estensioni (es. kimu-home).

---

Cos'è il modulo i18n?

Il modulo i18n fornisce servizi e strumenti per la localizzazione delle interfacce e la gestione dinamica delle lingue nell'applicazione.

Obiettivi

• Gestire la lingua globale dell'app
• Caricare e fornire traduzioni localizzate
• Offrire API semplici per tradurre stringhe e cambiare lingua a runtime

---

Struttura del modulo

src/
  modules/
    i18n/
      kimu-global-lang.ts      // Singleton per la lingua globale
      kimu-i18n-service.ts     // Servizio principale per traduzioni
      helpers.ts               // Funzioni di supporto (es. formatDate)
      resources/               // File di traduzioni (es. it.json, en.json)
      module.ts                // Entry point del modulo
      index.ts                 // Esporta tutto

---

Classi e servizi principali

KimuGlobalLang

• Singleton che gestisce la lingua globale dell'applicazione
• API: getLang(), setLang(lang), onChange(callback)
• Notifica i listener quando la lingua cambia

KimuI18nService

• Servizio principale per la traduzione
• API:
  • setLang(lang): cambia lingua e carica le traduzioni
  • getLang(): restituisce la lingua attiva
  • translate(key, params?): traduce una chiave, opzionalmente interpolando parametri
  • onChange(callback): notifica quando la lingua o le traduzioni cambiano

helpers.ts

• Funzioni di utilità per formattare date, numeri, ecc. secondo la lingua attiva

---

Come usare il modulo i18n

1. Caricamento tramite Module Manager

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

2. Impostare la lingua globale

i18nService.setLang('en');

3. Tradurre stringhe

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

4. Reagire al cambio lingua

i18nService.onChange(() => {
  // Aggiorna UI o ricarica dati localizzati
});

---

Esempio: integrazione in un'estensione (kimu-home)

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

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

  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 {
      // ...altri dati...
      translate: this.i18nService.translate,
    };
  }
}

---

Risorse e file di traduzione

• /src/modules/i18n/resources/it.json — traduzioni italiane
• /src/modules/i18n/resources/en.json — traduzioni inglesi

Formato tipico:

{
  "welcome": "Benvenuto!",
  "logout": "Esci"
}

---

Best practice

• Usa sempre il servizio i18n per tutte le stringhe visibili all’utente
• Aggancia la UI agli eventi di cambio lingua per aggiornare dinamicamente
• Mantieni le risorse di traduzione organizzate per lingua
• Evita di hardcodare stringhe nell’interfaccia