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