@mirta/i18n 0.0.1 → 0.4.0

package/dist/index.mjs

@@ -0,0 +1,815 @@
+import { resolve, join, basename } from 'node:path';
+import { readFile, glob } from 'node:fs/promises';
+
+/**
+ * Имя текущего пакета в формате, используемом в npm-реестре.
+ *
+ * @since 0.4.0
+ *
+ * @internal
+ *
+ **/
+const THIS_PACKAGE_NAME = '@mirta/i18n';
+/**
+ * Локаль по умолчанию (fallback), если параметр `options.fallbackLocale` не указан.
+ *
+ * @since 0.4.0
+ *
+ * @internal
+ *
+ **/
+const DEFAULT_FALLBACK_LOCALE = 'en-US';
+
+/**
+ * Специализированный класс для обработки ошибок, связанных с работой локализации.
+ *
+ * Предоставляет структурированные и типизированные ошибки с использованием кодов, что упрощает
+ * программную обработку исключений в инструментах, работающих с пакетами.
+ *
+ * @example
+ * ```ts
+ * throw LocalizationError.get('fallback.LoadFailed', 'en-US')
+ * ```
+ * @since 0.4.0
+ *
+ **/
+class LocalizationError extends Error {
+    /**
+     * Код ошибки для программной идентификации.
+     *
+     * Позволяет точно определить причину ошибки в обработчиках `try/catch`.
+     *
+     **/
+    code;
+    /**
+     * Приватный конструктор, используемый только внутри
+     * класса для создания экземпляров ошибки.
+     *
+     * @param message - Полное сообщение об ошибке.
+     * @param code - Код ошибки для идентификации.
+     * @param scope - Пространство имён или модуль, в котором возникла ошибка.
+     *                По умолчанию — {@link THIS_PACKAGE_NAME}.
+     *
+     **/
+    constructor(message, code, scope) {
+        super(`[${scope ?? THIS_PACKAGE_NAME}] ${message}`);
+        this.name = 'LocalizationError';
+        this.code = code;
+        // Захватываем стек вызовов, исключая фабричный метод `get`,
+        // чтобы улучшить читаемость трассировки.
+        //
+        if ('captureStackTrace' in Error)
+            Error.captureStackTrace(this, scope
+                // eslint-disable-next-line @typescript-eslint/unbound-method
+                ? LocalizationError.getScoped
+                // eslint-disable-next-line @typescript-eslint/unbound-method
+                : LocalizationError.get);
+    }
+    /** Карта кодов ошибок с соответствующими сообщениями. */
+    static codeMappings = {
+        'strict.invalidPluralValue': (variable, value) => `Expected number for "${variable}", got ${typeof value} (${JSON.stringify(value)})`,
+        'fallback.loadFailed': (locale) => `Failed to load fallback locale "${locale}"`,
+    };
+    /**
+     * Фабричный метод для создания экземпляра ошибки по её коду.
+     *
+     * Автоматически подставляет сообщение из `codeMappings` и формирует ошибку с заданными параметрами.
+     *
+     * @template T - Ограниченный ключами `codeMappings` тип, гарантирующий корректность кода.
+     * @param code - Код ошибки (например, `'fallback.loadFailed'`).
+     * @param args - Аргументы, соответствующие параметрам функции сообщения из `codeMappings`.
+     * @returns Новый экземпляр {@link LocalizationError} с шаблонным сообщением.
+     *
+     * @example
+     * ```ts
+     * const error = LocalizationError.get('fallback.loadFailed', 'en-US')
+     * ```
+     */
+    static get(code, ...args) {
+        const messageFn = this.codeMappings[code];
+        const message = messageFn(...args);
+        return new LocalizationError(message, code);
+    }
+    /**
+     * Фабричный метод, аналогичный `get`, но с возможностью указать
+     * пользовательское пространство имён (scope).
+     *
+     * Полезно при использовании в других модулях, где нужно указать
+     * иной контекст ошибки.
+     *
+     * @template TKey - Тип кода ошибки, аналогично `get`.
+     *
+     * @param scope - Пространство имён ошибки (например, `'@mirta/store'`).
+     * @param code - Код ошибки.
+     * @param args - Аргументы для формирования сообщения.
+     *
+     * @returns Новый экземпляр {@link LocalizationError} с пользовательским
+     *          префиксом и шаблонным сообщением.
+     *
+     * @example
+     *
+     * ```ts
+     * const error = LocalizationError.getScoped('@mirta/cli', 'fallback.loadFailed', 'en-US')
+     * ```
+     **/
+    static getScoped(scope, code, ...args) {
+        const messageFn = this.codeMappings[code];
+        const message = messageFn(...args);
+        return new LocalizationError(message, code, scope);
+    }
+}
+
+/**
+ * Специализированный класс для обработки ошибок, связанных с работой локализации.
+ *
+ * Предоставляет структурированные и типизированные ошибки с использованием кодов, что упрощает
+ * программную обработку исключений в инструментах, работающих с пакетами.
+ *
+ * @example
+ * ```ts
+ * throw SourceError.get('file.accessDenied', '/path/to/file')
+ * ```
+ * @since 0.4.0
+ *
+ **/
+class SourceError extends Error {
+    /**
+     * Код ошибки для программной идентификации.
+     *
+     * Позволяет точно определить причину ошибки в обработчиках `try/catch`.
+     *
+     **/
+    code;
+    /**
+     * Приватный конструктор, используемый только внутри
+     * класса для создания экземпляров ошибки.
+     *
+     * @param message - Полное сообщение об ошибке.
+     * @param code - Код ошибки для идентификации.
+     * @param scope - Пространство имён или модуль, в котором возникла ошибка.
+     *                По умолчанию — {@link THIS_PACKAGE_NAME}.
+     *
+     **/
+    constructor(message, code, scope) {
+        super(`[${scope ?? THIS_PACKAGE_NAME}] ${message}`);
+        this.name = 'SourceError';
+        this.code = code;
+        // Захватываем стек вызовов, исключая фабричный метод `get`,
+        // чтобы улучшить читаемость трассировки.
+        //
+        if ('captureStackTrace' in Error)
+            Error.captureStackTrace(this, scope
+                // eslint-disable-next-line @typescript-eslint/unbound-method
+                ? SourceError.getScoped
+                // eslint-disable-next-line @typescript-eslint/unbound-method
+                : SourceError.get);
+    }
+    /** Карта кодов ошибок с соответствующими сообщениями. */
+    static codeMappings = {
+        'file.notFound': (filePath) => `Locale file not found: "${filePath}"`,
+        'file.accessDenied': (filePath) => `Access denied to "${filePath}"`,
+        'file.failedToRead': (filePath, reason) => `Failed to read "${filePath}": ${reason ?? 'unknown reason'}`,
+        'file.nonCanonicalName': (filePath, locale) => `Locale file name "${filePath}" is not in canonical form. Expected "${locale}.json"`,
+        /**
+         * Ошибка парсинга JSON в файле локали.
+         *
+         * @param filePath - Путь к файлу с некорректным JSON.
+         * @param message - Сообщение об ошибке от парсера (например, `Unexpected token }`).
+         *
+         **/
+        'parse.invalidJson': (filePath, message) => `Invalid JSON in file "${filePath}": ${message}`,
+        /**
+         * Ошибка, когда корневой элемент JSON не является объектом (`{}`).
+         *
+         **/
+        'parse.invalidJsonRoot': () => 'Invalid JSON: root must be an object, not an array or primitive value',
+    };
+    static isFileError(error) {
+        return error instanceof SourceError && error.code.startsWith('file.');
+    }
+    static isParseError(error) {
+        return error instanceof SourceError && error.code.startsWith('parse.');
+    }
+    /**
+     * Фабричный метод для создания экземпляра ошибки по её коду.
+     *
+     * Автоматически подставляет сообщение из `codeMappings` и формирует ошибку с заданными параметрами.
+     *
+     * @template T - Ограниченный ключами `codeMappings` тип, гарантирующий корректность кода.
+     * @param code - Код ошибки (например, `'alreadyDefined'`).
+     * @param args - Аргументы, соответствующие параметрам функции сообщения из `codeMappings`.
+     * @returns Новый экземпляр {@link SourceError} с шаблонным сообщением.
+     *
+     * @example
+     * ```ts
+     * const error = SourceError.get('file.notFound', '/path/to/locale.json')
+     * ```
+     */
+    static get(code, ...args) {
+        const messageFn = this.codeMappings[code];
+        const message = messageFn(...args);
+        return new SourceError(message, code);
+    }
+    /**
+     * Фабричный метод, аналогичный `get`, но с возможностью указать
+     * пользовательское пространство имён (scope).
+     *
+     * Полезно при использовании в других модулях, где нужно указать
+     * иной контекст ошибки.
+     *
+     * @template TKey - Тип кода ошибки, аналогично `get`.
+     *
+     * @param scope - Пространство имён ошибки (например, `'@mirta/store'`).
+     * @param code - Код ошибки.
+     * @param args - Аргументы для формирования сообщения.
+     *
+     * @returns Новый экземпляр {@link SourceError} с пользовательским
+     *          префиксом и шаблонным сообщением.
+     *
+     * @example
+     *
+     * ```ts
+     * const error = SourceError.getScoped('@mirta/bot-remote', 'file.accessDenied', '/path/to/file')
+     * ```
+     **/
+    static getScoped(scope, code, ...args) {
+        const messageFn = this.codeMappings[code];
+        const message = messageFn(...args);
+        return new SourceError(message, code, scope);
+    }
+}
+
+/**
+ * Кэш загруженных сообщений по локалям.
+ *
+ * Хранит:
+ * - `object` — успешно загруженные и замороженные сообщения
+ * - `null` — признак того, что загрузка для этой локали уже провалилась (избежание повторных попыток)
+ *
+ * @private
+ *
+ **/
+const loadedMessages = new Map();
+/**
+ * Парсит JSON и возвращает объект.
+ * Ожидает валидный JSON с корневым объектом.
+ *
+ * @param content - JSON-строка
+ * @returns Объект сообщений
+ * @throws {SourceError} Если JSON — не объект
+ *
+ * @since 0.4.0
+ *
+ **/
+function parseLocaleJson(content) {
+    const parsed = JSON.parse(content);
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed))
+        throw SourceError.get('parse.invalidJsonRoot');
+    return parsed;
+}
+/**
+ * Читает и парсит JSON-файл с сообщениями локали.
+ *
+ * Ожидает валидный UTF-8 и корректный JSON.
+ * Результат замораживается для защиты от изменений.
+ *
+ * @param filePath - Путь к файлу `.json`.
+ * @returns Объект сообщений.
+ * @throws {SourceError} С кодами `file.notFound`, `file.accessDenied`, `parse.invalidJson` и др.
+ *
+ **/
+async function readLocaleFileAsync(filePath) {
+    try {
+        const content = await readFile(filePath, 'utf-8');
+        return Object.freeze(parseLocaleJson(content));
+    }
+    catch (e) {
+        if (e instanceof SourceError)
+            throw e;
+        if (e instanceof SyntaxError)
+            throw SourceError.get('parse.invalidJson', filePath, e.message);
+        if (e && typeof e === 'object' && 'code' in e) {
+            switch (e.code) {
+                case 'ENOENT':
+                    throw SourceError.get('file.notFound', filePath);
+                case 'EACCES':
+                case 'EPERM':
+                    throw SourceError.get('file.accessDenied', filePath);
+            }
+        }
+        const message = e instanceof Error
+            ? e.message
+            : String(e);
+        throw SourceError.get('file.failedToRead', filePath, message);
+    }
+}
+/**
+ * Загружает сообщения для указанной локали.
+ *
+ * Использует кэш: повторные вызовы не читают файл.
+ * При неудаче кэшируется `null` — попытки не повторяются.
+ *
+ * @param locale - Локаль в формате `xx-XX` (например, `ru-RU`).
+ * @param cwd - Базовая директория (обычно `process.cwd()`).
+ * @returns Сообщения или `null`, если загрузить не удалось.
+ *
+ * @remarks
+ * Ошибки, связанные с отсутствием файла (`file.notFound`), перехватываются.
+ *
+ * Остальные ошибки (невалидный JSON, нет доступа) пробрасываются,
+ * поскольку указывают на критические проблемы.
+ *
+ * @since 0.4.0
+ *
+ **/
+async function loadMessagesAsync(locale, cwd) {
+    let messages = loadedMessages.get(locale);
+    if (messages || messages === null)
+        return messages;
+    const filePath = resolve(cwd, './locales', `${locale}.json`);
+    try {
+        messages = await readLocaleFileAsync(filePath);
+        loadedMessages.set(locale, messages);
+        return messages;
+    }
+    catch (e) {
+        if (SourceError.isFileError(e) && e.code === 'file.notFound') {
+            loadedMessages.set(locale, null);
+            return null;
+        }
+        throw e;
+    }
+}
+
+/**
+ * Сканирует директорию `localesDir` и возвращает множество доступных локалей.
+ * Игнорирует отсутствие директории или файлов. Проверяет валидность локалей через `resolveLocale`.
+ *
+ * @param localesDir - Путь к папке с локалями (обычно `./locales`)
+ * @returns Множество валидных локалей (например, `Set { 'en-US', 'ru-RU' }`)
+ *
+ * @since 0.4.0
+ *
+ **/
+async function resolveSupportedLocalesAsync(localesDir) {
+    const pattern = join(localesDir, '*.json');
+    const locales = new Set();
+    try {
+        for await (const filePath of glob(pattern)) {
+            const localeSource = basename(filePath, '.json');
+            const locale = resolveLocale(localeSource);
+            if (!locale)
+                continue;
+            if (locale !== localeSource)
+                throw SourceError.get('file.nonCanonicalName', filePath, locale);
+            locales.add(locale);
+        }
+    }
+    catch (e) {
+        if (e && typeof e === 'object' && 'code' in e && e.code === 'ENOENT')
+            return locales;
+        throw e;
+    }
+    return locales;
+}
+/**
+ * Извлекает языковой код из локали (например, 'ru' из 'ru-RU').
+ *
+ * @param locale - Локаль в формате xx-XX
+ * @returns Языковой код (xx)
+ *
+ * @since 0.4.0
+ *
+ **/
+function getLang(locale) {
+    return locale.split('-')[0];
+}
+/**
+ * Загружает ассет локали: сообщения, язык и локаль.
+ * Возвращает `undefined`, если сообщения не найдены.
+ * Результат замораживается для неизменяемости.
+ *
+ * @template TShape - Интерфейс локали
+ *
+ * @param locale - Локаль (например, `'en-US'`)
+ * @param cwd - Рабочая директория
+ *
+ * @returns Ассет локали или `undefined`
+ *
+ * @since 0.4.0
+ *
+ **/
+async function loadAssetAsync(locale, cwd) {
+    const messages = await loadMessagesAsync(locale, cwd);
+    if (!messages)
+        return;
+    return Object.freeze({
+        locale,
+        lang: getLang(locale),
+        messages,
+    });
+}
+function resolveLocale(input, defaultLocale) {
+    if (!input || typeof input !== 'string')
+        return defaultLocale;
+    // Специальный случай в Unix-подобных системах (POSIX)
+    if (input === 'C')
+        return defaultLocale;
+    // Приведение к нижнему регистру для сравнения.
+    const normalizedInput = input
+        .trim()
+        .toLowerCase();
+    if (normalizedInput === 'en' || normalizedInput.startsWith('en-'))
+        return 'en-US';
+    if (normalizedInput === 'ru' || normalizedInput.startsWith('ru-'))
+        return 'ru-RU';
+    try {
+        // Защитная попытка нормализовать через Intl.
+        return Intl.getCanonicalLocales(input.trim())[0];
+    }
+    catch {
+        return defaultLocale;
+    }
+}
+/**
+ * Асинхронно устанавливает локаль в контексте.
+ * Если сообщения для локали недоступны, используется fallback.
+ *
+ * @param locale - Целевая локаль
+ * @param context - Контекст локализации
+ *
+ * @since 0.4.0
+ *
+ **/
+async function setLocaleAsync(locale, context) {
+    const fallbackAsset = context.fallbackAsset;
+    const targetLocale = resolveLocale(locale, fallbackAsset.locale);
+    // TODO: Добавить debug-логирование при переходе к fallbackAsset.
+    // Защищает от попыток загрузки и кэширования несуществующих ассетов.
+    const effectiveAsset = context.supportedLocales.has(targetLocale)
+        ? await loadAssetAsync(targetLocale, context.cwd) ?? fallbackAsset
+        : fallbackAsset;
+    context.locale = effectiveAsset.locale;
+    context.lang = effectiveAsset.lang;
+    context.messages = effectiveAsset.messages;
+}
+/**
+ * Получает системную локаль из переменных окружения или Intl.
+ *
+ * @returns Локаль в формате xx-XX (например, 'ru-RU')
+ *
+ * @since 0.4.0
+ *
+ **/
+function getSystemLocale() {
+    const rawLocale = process.env.LC_ALL
+        || process.env.LC_MESSAGES
+        || process.env.LANG
+        || Intl.DateTimeFormat().resolvedOptions().locale;
+    return rawLocale.split('.')[0].replaceAll('_', '-');
+}
+
+/**
+ * Определяет форму множественного числа для заданного языка и числа.
+ *
+ * Поддерживает:
+ * - Русский (`ru`): `one`, `few`, `many`
+ * - Английский и прочие: `one` (если 1), иначе `other`
+ *
+ * @param lang - Языковой код (например, 'ru', 'en')
+ * @param count - Число, для которого определяется форма
+ *
+ * @returns Одна из форм множественного числа (см. {@link PluralForm})
+ *
+ * @since 0.4.0
+ *
+ **/
+function getPluralForm(lang, count) {
+    if (lang === 'ru') {
+        // Если дробное — всегда 'few' (родительный падеж ед. числа)
+        if (!Number.isInteger(count))
+            return 'few';
+        const absCount = Math.floor(Math.abs(count));
+        const mod10 = absCount % 10;
+        const mod100 = absCount % 100;
+        if (mod10 === 1 && mod100 !== 11)
+            return 'one';
+        if (mod10 >= 2 && mod10 <= 4 && (mod100 < 10 || mod100 >= 20))
+            return 'few';
+        return 'many';
+    }
+    return count === 1 ? 'one' : 'other';
+}
+/**
+ * Извлекает сбалансированный блок `{...}` с учётом вложенности.
+ *
+ * @param message - Строка для поиска.
+ * @param index - Позиция, с которой начинается блок `{`.
+ * @param limit - Ограничение по длине строки.
+ *
+ * @returns Объект с `content` (содержимым) и `end` (индексом после `}`) или `null`, если блок несбалансирован.
+ *
+ * @example
+ * extractBalanced('{hello}', 0, 7) // → { content: 'hello', end: 7 }
+ *
+ * @example
+ * extractBalanced('{a{b}c}', 0, 7) // → { content: 'a{b}c', end: 7 }
+ *
+ * @example
+ * extractBalanced('{unclosed', 0, 9) // → null
+ *
+ * @since 0.4.0
+ *
+ **/
+function extractBalanced(message, index, limit) {
+    if (message[index] !== '{')
+        return null;
+    let depth = 1;
+    let i = index + 1;
+    while (i < limit && depth > 0) {
+        if (message[i] === '{')
+            depth++;
+        else if (message[i] === '}')
+            depth--;
+        i++;
+    }
+    if (depth !== 0)
+        return null;
+    return {
+        end: i,
+        content: message.slice(index + 1, i - 1),
+    };
+}
+/**
+ * Подставляет значения переменных в строку вида `{ключ}`.
+ *
+ * @param text - Строка с плейсхолдерами.
+ * @param variables - Объект с данными для подстановки.
+ *
+ * @returns Строка с заменёнными значениями или оригинальные плейсхолдеры, если значения не найдены.
+ *
+ * @example
+ * interpolate('Привет, {name}!', { name: 'Мира' }) // → 'Привет, Мира!'
+ *
+ * @example
+ * interpolate('Значение: {missing}', {}) // → 'Значение: {missing}'
+ *
+ * @since 0.4.0
+ *
+ **/
+function interpolate(text, variables) {
+    let result = '';
+    let pos = 0;
+    let start = 0;
+    const len = text.length;
+    while (pos < len) {
+        if (text[pos] === '{') {
+            result += text.slice(start, pos);
+            const block = extractBalanced(text, pos, len);
+            if (!block) {
+                result += '{';
+                pos++;
+                start = pos;
+                continue;
+            }
+            const { content, end } = block;
+            const value = variables?.[content];
+            result += value != null ? String(value) : `{${content}}`;
+            pos = end;
+            start = pos;
+        }
+        else {
+            pos++;
+        }
+    }
+    result += text.slice(start);
+    return result;
+}
+/**
+ * Разбирает часть сообщения с формами множественного числа (например, `one{...} other{...}`).
+ *
+ * Извлекает ключи (`one`, `other`, `=0` и т.д.) и соответствующие им содержимое,
+ * корректно обрабатывая вложенность фигурных скобок. Поддерживает точные значения (`=n`) и
+ * преобразует `two` в `few` в соответствии с правилами ICU.
+ *
+ * @param formsPart - Строка, содержащая последовательность `ключ{...}`.
+ *
+ * @returns Объект с двумя полями:
+ * - `exactForms` — карта точных значений (`=n`) и их содержимого;
+ * - `commonForms` — карта именованных форм (`one`, `other` и др.).
+ *
+ * @since 0.4.0
+ *
+ **/
+function parseFormsPart(formsPart) {
+    const exactForms = {};
+    const commonForms = {};
+    let pos = 0;
+    let keyBuffer = ''; // будем набирать ключ
+    const len = formsPart.length;
+    while (pos < len) {
+        const char = formsPart[pos];
+        if (char === '{') {
+            // Встретили `{` → текущий буфер — это ключ
+            const key = keyBuffer.trim();
+            keyBuffer = '';
+            if (!key) {
+                // Пустой ключ — пропускаем
+                pos++;
+                continue;
+            }
+            // Извлекаем сбалансированное тело
+            const block = extractBalanced(formsPart, pos, len);
+            if (!block) {
+                pos++;
+                continue;
+            }
+            // Сохраняем
+            if (key.startsWith('=')) {
+                const num = parseInt(key.slice(1), 10);
+                exactForms[num] = block.content;
+            }
+            else {
+                // ICU: 'two' → treat as 'few'
+                const formKey = key === 'two' ? 'few' : key;
+                commonForms[formKey] = block.content;
+            }
+            // Продолжаем после блока
+            pos = block.end;
+        }
+        else {
+            // Накапливаем символы в буфере
+            keyBuffer += char;
+            pos++;
+        }
+    }
+    return { exactForms, commonForms };
+}
+/**
+ * Обрабатывает конструкцию `plural` в формате ICU.
+ *
+ * @param content - Содержимое блока, например: `count, plural, one{...} other{...}`.
+ * @param variables - Переменные для подстановки значений.
+ * @param context - Контекст локализации (язык, strict-режим).
+ *
+ * @returns Обработанную строку с нужной формой и подставленным числом, или ошибку в strict-режиме.
+ *
+ * @since 0.4.0
+ *
+ **/
+function parsePlural(content, variables, context) {
+    // Парсим: {count, plural, offset:1, one{...} other{...}}
+    const match = /([^}]+),\s*plural,\s*(?:offset:(\d+)\s*)?(.+)/g.exec(content);
+    if (!match) {
+        if (context.strict)
+            throw new Error('Invalid plural format');
+        return '';
+    }
+    const [, variable, offsetPart, formsPart] = match;
+    const offset = offsetPart ? parseInt(offsetPart, 10) : 0;
+    const originalValue = Number(variables?.[variable]);
+    if (isNaN(originalValue)) {
+        if (context.strict)
+            throw LocalizationError.get('strict.invalidPluralValue', variable, variables?.[variable]);
+        return 'NaN';
+    }
+    const value = originalValue - offset;
+    const { exactForms, commonForms } = parseFormsPart(formsPart);
+    // Обрабатываем =0{...}, =1{...}
+    if (value in exactForms)
+        return exactForms[value].replace(/#/g, String(value));
+    // Обрабатываем one{...}, few{...}, other{...}
+    const form = getPluralForm(context.lang, value);
+    const formText = commonForms[form] ?? commonForms.other ?? '';
+    return formText.replace(/#/g, String(value));
+}
+/**
+ * Создаёт функцию перевода на основе текущего контекста локализации.
+ *
+ * Поддерживает:
+ * - Подстановку переменных: `{name}`
+ * - Множественные формы: `{count, plural, one{...} other{...}}`
+ * - Смещение (offset): `{count, plural, offset:1, one{...} other{...}}`
+ * - Точные значения: `=0{...}`
+ *
+ * @param context - Контекст локализации с сообщениями и языком
+ * @returns Функция перевода `translate(key, variables?)`
+ *
+ * @since 0.4.0
+ *
+ **/
+function createTranslator(context) {
+    const translate = (key, variables) => {
+        const message = context.messages[key] ?? context.fallbackAsset.messages[key];
+        if (!message)
+            return `{{${key}}}`;
+        let result = '';
+        let pos = 0;
+        let start = 0;
+        const len = message.length;
+        // Основной цикл
+        while (pos < len) {
+            if (message[pos] === '{') {
+                // Добавить текст до {
+                result += message.slice(start, pos);
+                const block = extractBalanced(message, pos, len);
+                if (!block) {
+                    result += '{';
+                    pos++;
+                    start = pos;
+                    continue;
+                }
+                const { content, end } = block;
+                if (/^\s*[a-zA-Z0-9_.-]+\s*,\s*plural\b/.test(content)) {
+                    result += interpolate(parsePlural(content, variables, context), variables);
+                }
+                else {
+                    // Простая переменная: {name}
+                    const value = variables?.[content];
+                    result += value != null ? String(value) : `{${content}}`;
+                }
+                pos = end;
+                start = pos;
+            }
+            else {
+                pos++;
+            }
+        }
+        // Добавить остаток
+        result += message.slice(start);
+        return result;
+    };
+    translate.plain = (key, fallbackValue) => {
+        const message = context.messages[key]
+            ?? context.fallbackAsset.messages[key]
+            ?? fallbackValue
+            ?? `{{${key}}}`;
+        return message;
+    };
+    return translate;
+}
+
+/**
+ * Инициализирует систему локализации, загружает сообщения для системной и fallback-локали.
+ *
+ * @template TShape - Интерфейс локали, описывающий структуру сообщений и переменных.
+ *                    Если не указан, применяется тип {@link GenericShape}, разрешающий использовать любые строки как ключи.
+ *                    Для включения строгой типизации передайте сгенерированный или явно определённый интерфейс `LocaleShape`.
+ *
+ * @param options - Опции инициализации локализации.
+ * @param options.cwd - Рабочая директория, откуда загружаются локали (по умолчанию: `process.cwd()`).
+ * @param options.fallbackLocale - Локаль по умолчанию, если другие не найдены (по умолчанию: `'en-US'`).
+ *
+ * @returns Промис, разрешающийся в объект `Localization<TShape>`, содержащий:
+ * - `getLocale()` — текущую локаль
+ * - `setLocaleAsync(locale)` — переключение локали
+ * - `t(key, vars)` — функция перевода
+ *
+ * @throws Ошибка, если не удалось загрузить fallback-локаль.
+ *
+ * @example
+ * ```ts
+ * // Без LocaleShape — нет строгой проверки ключей
+ * const { t } = await initLocalizationAsync()
+ * t('non.existing.key') // OK (нет ошибки на уровне типов)
+ * ```
+ *
+ * @example
+ * ```ts
+ * // С интерфейсом — полная типизация
+ * const { t } = await initLocalizationAsync<MyLocaleShape>()
+ * t('non.existing.key') // Ошибка компиляции
+ * ```
+ *
+ * @since 0.4.0
+ *
+ **/
+async function initLocalizationAsync(options = {}) {
+    const cwd = options.cwd ?? process.cwd();
+    const fallbackLocale = resolveLocale(options.fallbackLocale, DEFAULT_FALLBACK_LOCALE);
+    const fallbackAsset = await loadAssetAsync(fallbackLocale, cwd);
+    if (!fallbackAsset)
+        throw LocalizationError.get('fallback.loadFailed', fallbackLocale);
+    const systemLocale = resolveLocale(getSystemLocale(), fallbackLocale);
+    const effectiveAsset = await loadAssetAsync(systemLocale, cwd) ?? fallbackAsset;
+    const localesDir = join(cwd, 'locales');
+    const supportedLocales = await resolveSupportedLocalesAsync(localesDir);
+    const context = {
+        strict: options.strict ?? false,
+        cwd,
+        fallbackAsset,
+        supportedLocales,
+        lang: effectiveAsset.lang,
+        locale: effectiveAsset.locale,
+        messages: effectiveAsset.messages,
+    };
+    return {
+        getLocale: () => context.locale,
+        setLocaleAsync: async (locale) => {
+            await setLocaleAsync(locale, context);
+        },
+        t: createTranslator(context),
+    };
+}
+
+export { LocalizationError, SourceError, initLocalizationAsync };