Skip to content

I18nService

This file defines the I18nService class, which provides internationalization (i18n) support for the @sodacore/core framework. It is responsible for loading translation files, managing available translations, and providing methods for translating strings and querying available languages.


Features

  • Translation File Loading: Automatically loads all JSON translation files from a configurable directory.
  • Translation Lookup: Translates keys to localized strings for a given language code, with fallback support.
  • Language Management: Tracks available languages and provides a method to list them.
  • Error Handling: Logs errors for missing translation files or failed loads.
  • Configurable Paths: Supports custom translation directories via configuration.

Usage

typescript
import I18nService from './service/i18n';

const i18nService = new I18nService();
await i18nService.init();

const greeting = i18nService.translate('hello.world', 'fr', 'Hello, world!');
const availableLanguages = i18nService.getAvailableLanguages();

API

Properties

  • config: Optional i18n configuration, injected via DI.
  • translationsPath: Path to the directory containing translation files.
  • _hasTranslations: Boolean indicating if any translations are loaded.
  • translations: Record of loaded translations, keyed by language code.

Methods

async init(): Promise<void>

Initializes the service:

  • Resolves the translations directory.
  • Loads all translation files.
  • Populates the translations property.

hasTranslations(): boolean

Returns true if translations have been loaded, otherwise false.

translate(query: string, languageCode: string, fallback?: string): string

Translates a key for the specified language code. Returns the translation, the fallback, or the original query if not found.

getAvailableLanguages(lower?: boolean): string[]

Returns an array of available language codes, including the default language.

private async getFilePaths(): Promise<string[] | null>

Scans the translations directory for .json files and returns their absolute paths.

private async loadTranslations(filePaths: string[]): Promise<Record<string, ITranslation>>

Loads and parses translation files, building the translations record.


How It Works

  1. Initialization:

    • Determines the translations directory from config or defaults to ./translations.
    • Scans for all .json files in the directory.
    • Loads each file, extracting the language code from the filename (e.g., en-GB.json).
    • Populates the translations object with the loaded data.
  2. Translation:

    • Looks up the translation for a given key and language code.
    • Returns the translation if found, otherwise returns the fallback or the original key.
  3. Language Listing:

    • Returns all available language codes, including the default language.

Notes

  • Translation files must be named using the format lang-COUNTRY.json (e.g., en-GB.json).
  • Each translation file should export a JSON object mapping keys to translated strings.
  • The service logs errors for missing or malformed translation files.
  • Designed for use with the Sodacore dependency injection and service lifecycle.

Released under the Apache-2.0 License.