Foundation i18n

The @genesislcap/foundation-i18n package provides a collection of i18n services and utilities for Genesis applications. It leverages the power of i18next to enable seamless internationalization and localization.

API Documentation

For more detailed information on API and configurations, please refer to the API documentation.

Features

• Easy integration: Quick setup with modern JavaScript frameworks and libraries.
• Dynamic language switching: Change languages on the fly without reloading the application.
• Module federation support: Share and load translations across different micro-frontends or modules dynamically.
• Dependency injection: Integrate i18n services into your components using dependency injection.

Getting Started

Installation

To enable this module in your application, follow the steps below.

1. Add @genesislcap/foundation-i18n as a dependency in your package.json file. Whenever you change the dependencies of your project, ensure you run the $ npm run bootstrap command again. You can find more information in the package.json basics page.

{
  "dependencies": {
    "@genesislcap/foundation-i18n": "latest"
  },
}

I18n Setup

Import the necessary modules from @genesislcap/foundation-i18n and configure your internationalization settings.

import { defaultI18nextConfig, I18nextConfig } from '@genesislcap/foundation-i18n';

// Tip: Extend or modify the defaultI18nextConfig as needed.
Registration.instance<I18nextConfig>(I18nextConfig, {
  ...defaultI18nextConfig,
  lng: 'pt', // en is the default language but you can change it here or by tweaking the defaultI18nextConfig
  resources: {
    en: {
      translation: {
        Home: 'Home',
        Admin: 'Admin',
        Reporting: 'Reporting',
        Notifications: 'Notifications',
        ['Features Lab']: 'Features Lab',
      },
    },
    pt: {
      translation: {
        Home: 'Início',
        Admin: 'Administração',
        Reporting: 'Relatórios',
        Notifications: 'Notificações',
        ['Features Lab']: 'Laboratório de Funcionalidades',
      },
    },
  },
});

This could live in your application’s entry point, such as main.ts or a similar file.

I18n Setup (JSON)

You can also use a JSON file to store your translations and load them dynamically:

{
  "en": {
    "translation": {
      "Home": "Home",
      "Admin": "Admin",
      "Reporting": "Reporting",
      "Notifications": "Notifications",
      "Features Lab": "Features Lab"
    }
  },
  "pt": {
    "translation": {
      "Home": "Início",
      "Admin": "Administração",
      "Reporting": "Relatórios",
      "Notifications": "Notificações",
      "Features Lab": "Laboratório de Funcionalidades"
    }
  }
}

Then, import the JSON file and use it in your configuration:

import { defaultI18nextConfig, I18nextConfig } from '@genesislcap/foundation-i18n';
import translations from './translations.json';

Registration.instance<I18nextConfig>(I18nextConfig, {
  ...defaultI18nextConfig,
  lng: 'en',
  resources: translations,
});

addResources

⚠️ This will overwrite previously set resources.

You can also add resources dynamically and when necessary.

This is useful when you have a large number of translations or when you need to load translations from a different source or at a different time from the initial setup.

import { I18next } from '@genesislcap/foundation-i18n';
import translations from './translations.json';

export class MyExampleClass {
  @I18next i18next!: I18next;

  addResources() {
    this.i18next.addResources(translations);
  }
}

Usage

foundation-i18n also supports changing languages dynamically, allowing your application to switch languages without needing to reload:

import { I18next } from '@genesislcap/foundation-i18n';
import { customElement, FASTElement, html } from '@microsoft/fast-element';
import translations from './translations.json';

@customElement({
  name: 'my-example-component',
  template: html`
    <zero-button @click=${() => addResources()}>Add Translation Resources</zero-button>
    <zero-button @click=${() => switchLanguage()}>Switch between PT and EN</zero-button>
    <zero-button @click=${() => translateWords()}>Translate i18n Resource Words</zero-button>
  `,
})
export class MyExampleComponent extends FASTElement {
  @I18next i18next!: I18next;

  addResources() {
    this.i18next.addResources(translations);
  }

  switchLanguage() {
    if (this.i18next.language === 'pt') {
      this.i18next.changeLanguage('en');
    } else {
      this.i18next.changeLanguage('pt');
    }
  }

  translateWords() {
    console.log(this.i18next.t('Home')); // if pt, it will log Início, if en, it will log Home
    console.log(this.i18next.t('Admin')); // if pt, it will log Administração, if en, it will log Admin
    console.log(this.i18next.t('Reporting')); // if pt, it will log Relatórios, if en, it will log Reporting
    console.log(this.i18next.t('Notifications')); // if pt, it will log Notificações, if en, it will log Notifications
    console.log(this.i18next.t('Features Lab')); // if pt, it will log Laboratório de Funcionalidades, if en, it will log Features Lab
  }
}

Integrating with Other Libraries

Angular Example

To integrate @genesislcap/foundation-i18n with an Angular application, you can configure i18next in a service and use it throughout your components.

i18n.service.ts

import { Injectable } from '@angular/core';
import { defaultI18nextConfig, I18next } from '@genesislcap/foundation-i18n';
import translations from './translations.json';
import { DI } from '@microsoft/fast-element';

@Injectable({
  providedIn: 'root',
})
export class I18nService {
  private container = DI.getOrCreateDOMContainer();
  private i18n = this.container.get(I18nService);

  constructor() {
    this.i18n.init({
      ...defaultI18nextConfig,
      lng: 'en',
      resources: translations,
    });
  }

  switchLanguage() {
    const newLanguage = this.i18n.language === 'en' ? 'pt' : 'en';
    this.i18n.changeLanguage(newLanguage);
  }

  translate(key: string): string {
    return this.i18n.t(key);
  }
}

app.component.ts

import { Component } from '@angular/core';
import { I18nService } from './i18n.service';

@Component({
  selector: 'app-root',
  template: `
    <button (click)="switchLanguage()">Switch Language</button>
    <p>{{ translate('Home') }}</p>
    <p>{{ translate('Admin') }}</p>
    <p>{{ translate('Reporting') }}</p>
  `,
})
export class AppComponent {
  constructor(private i18nService: I18nService) {}

  switchLanguage() {
    this.i18nService.switchLanguage();
  }

  translate(key: string): string {
    return this.i18nService.translate(key);
  }
}

React Example

To integrate @genesislcap/foundation-i18n with a React application, you can create a separate service for handling i18next similar to how you would create other services.

i18nService.js

import { defaultI18nextConfig, I18next } from '@genesislcap/foundation-i18n';
import { DI } from '@microsoft/fast-foundation';
import translations from './translations.json';

class I18nService {
  private container = DI.getOrCreateDOMContainer();
  private i18n: Connect = this.container.get(I18next);

  constructor() {
    this.i18n.init({
      ...defaultI18nextConfig,
      lng: 'en',
      resources: translations,
    });
  }

  switchLanguage() {
    const newLanguage = this.i18n.language === 'en' ? 'pt' : 'en';
    this.i18n.changeLanguage(newLanguage);
  }

  translate(key) {
    return this.i18n.t(key);
  }
}

export const i18nService = new I18nService();

App.js

import React from 'react';
import { i18nService } from './i18nService';

const App = () => {
  const switchLanguage = () => {
    i18nService.switchLanguage();
  };

  return (
    <div>
      <button onClick={switchLanguage}>Switch Language</button>
      <p>{i18nService.translate('Home')}</p>
      <p>{i18nService.translate('Admin')}</p>
      <p>{i18nService.translate('Reporting')}</p>
    </div>
  );
};

export default App;