Skip to content

I18nService

This file defines the I18nService class, which provides the core internationalization (i18n) functionality for the @sodacore/core framework. It is responsible for loading translation files, managing available languages, and providing translation lookup for the application.


Features

  • Translation File Loading: Scans a configurable directory for JSON translation files and loads them into memory.
  • Translation Lookup: Provides methods to translate keys for a given language, with support for fallbacks.
  • Available Languages Management: Tracks and exposes the list of available languages based on loaded translation files.
  • Configurable Paths: Supports custom translation directory paths via configuration.
  • Dependency Injection: Uses @Service and @Inject decorators for integration with the Sodacore DI system.
  • Error Logging: Logs errors for missing files, failed loads, or missing translations.

Usage

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

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

const translated = i18nService.translate('greeting.hello', 'en-GB', 'Hello');
const languages = i18nService.getAvailableLanguages();

API

Methods

async init(): Promise<void>

Initializes the service by resolving the translations directory, loading all translation files, and logging the results.

hasTranslations(): boolean

Returns true if any translations have been loaded, otherwise false.

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

Returns the translation for the given key and language code. If not found, returns the fallback or the original query.

getAvailableLanguages(lower?: boolean): string[]

Returns an array of available language codes. If lower is true, returns all codes in lowercase.


Private Methods

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 each translation file, mapping them by language code.


How It Works

  1. Initialization:

    • Determines the translations directory from config or defaults to ./translations.
    • Uses Bun's Glob to find all .json translation files.
    • Loads each file, parsing its contents and extracting the language code from the filename.
    • Stores all translations in memory and marks translations as available if any are found.
  2. Translation Lookup:

    • Checks if translations are loaded.
    • Looks up the translation for the given key and language code.
    • Returns the fallback or the original key if not found.
  3. Language Management:

    • Returns the list of available languages, always including the default language from config.

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.
  • Designed to be used as a service within the Sodacore dependency injection system.
  • Uses Bun's file and glob APIs for file operations.

Released under the Apache-2.0 License.