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
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
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.
- Determines the translations directory from config or defaults to
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.
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.