@mirta/i18n 0.0.1 → 0.4.1

package/LICENSE

@@ -0,0 +1,24 @@
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org>

package/README.md

@@ -1,45 +1,242 @@
 # @mirta/i18n
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+[![en](https://img.shields.io/badge/lang-en-olivedrab.svg?style=flat-square)](https://github.com/wb-mirta/core/blob/latest/packages/mirta-i18n/README.md)
+[![ru](https://img.shields.io/badge/lang-ru-dimgray.svg?style=flat-square)](https://github.com/wb-mirta/core/blob/latest/packages/mirta-i18n/README.ru.md)
+[![NPM Version](https://img.shields.io/npm/v/@mirta/i18n?style=flat-square)](https://npmjs.com/package/@mirta/i18n)
+[![NPM Downloads](https://img.shields.io/npm/dm/@mirta/i18n?style=flat-square&logo=npm)](https://npmjs.com/package/@mirta/i18n)
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+> Localization library for Mirta Framework CLI tools, with ICU-compatible syntax.
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+The `@mirta/i18n` package is intended exclusively for **Node.js tools** (≥ 20.6.0) and is not used in the Duktape runtime.
 
-## Purpose
+## Features
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@mirta/i18n`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+- ✔️ Type-safe keys and variables — when a `LocaleShape` is provided
+- ✔️ ICU-compatible syntax: `{var}`, `{count, plural, ...}`, `offset`, `=n`, `#`
+- ✔️ Asynchronous loading and caching of `.json` files
+- ✔️ Zero dependencies — minimal footprint
+- ✔️ Configurable fallback (en-US by default)
+- ✔️ Unified translation contract `t(key, vars)`
 
-## What is OIDC Trusted Publishing?
+## 📦 Installation
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+```sh
+pnpm add @mirta/i18n
+```
 
-## Setup Instructions
+⚠️ This package is part of Mirta Framework's internal infrastructure. It is typically not used directly.
 
-To properly configure OIDC trusted publishing for this package:
+## Usage
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+### 1. Organize the locale structure
 
-## DO NOT USE THIS PACKAGE
+Set up the localization structure for your package:
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+```txt
+<package>/
+  locales/
+    en-US.json
+    ru-RU.json
+```
 
-## More Information
+Example `en-US.json`:
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+```json
+{
+  "title": "Welcome",
+  "files.plural": "{count, plural, =0{No files} one{One file} other{# files}}",
+  "greeting": "Hello, {name}!"
+}
+```
+
+### 2. Define the `LocaleShape`
+
+To enable type safety, define an interface compatible with `GenericShape`:
+
+```ts
+interface LocaleShape {
+  messages: {
+    'title': string;
+    'files.plural': string;
+    'greeting': string;
+  };
+  variables: {
+    'files.plural': { count: number };
+    'greeting': { name: string };
+  };
+}
+```
+
+💡 The `LocaleShape` type must be defined in the project.  
+Mirta Framework uses an internal script to generate it from `locales/en-US.json`.
+
+⚠️ If no locale shape is provided, `GenericShape` is used — keys and variables are not type-checked.
+
+### 3. Initialize localization
+
+In the package to be localized:
+
+```ts
+// src/i18n/index.ts
+import { initLocalizationAsync } from '@mirta/i18n'
+
+export const { t, setLocaleAsync } = await initLocalizationAsync<LocaleShape>()
+```
+
+### 4. Use translation
+
+```ts
+console.log(t('title')) // → "Welcome"
+console.log(t('greeting', { name: 'Alice' })) // → "Hello, Alice!"
+console.log(t('files.plural', { count: 5 })) // → "5 files"
+```
+
+Changing locale:
+
+```ts
+await setLocaleAsync('ru-RU')
+console.log(t('title')) // → "Добро пожаловать"
+```
+
+## 📚 API
+
+### `initLocalizationAsync<TShape>(options)`
+
+Initializes the localization subsystem.
+
+#### Parameters
+
+| Field | Type | Description |
+|------|-----|----------|
+| `cwd` | `string` | Working directory (default: `process.cwd()`) |
+| `fallbackLocale` | `string` | Fallback locale (default: `'en-US'`) |
+
+#### Returns
+
+`Promise<Localization<TShape>>`
+
+#### Errors
+
+- `fallback.LoadFailed` — if the fallback locale cannot be loaded.
 
 ---
 
-**Maintained for OIDC setup purposes only**
+### `Localization<TShape>`
+
+| Method | Type | Description |
+|------|-----|----------|
+| `t(key, vars?)` | `(key: K, vars?: VariablesOf<TShape, K>) => string` | Type-safe translation function |
+| `getLocale()` | `() => Locale` | Returns current locale |
+| `setLocaleAsync(locale)` | `(locale: string) => Promise<void>` | Changes locale (normalizes and caches) |
+
+---
+
+### `Locale`
+
+Type: `Branded<string, 'Locale'>` — branded locale type.
+
+### `Lang`
+
+Type: `Branded<string, 'Lang'>` — branded language type.
+
+## Key Features
+
+### ✅ Optional type safety
+
+The `t()` function ensures type safety **only when `LocaleShape` is provided**:
+
+- Validates key existence
+- Enforces required variables
+- Prevents extra fields
+
+```ts
+t('files.plural', { count: 2 }) // ✅
+t('files.plural', {})           // ❌ Error: missing `count`
+t('title', { name: 'John' })    // ❌ Error: `title` does not accept variables
+```
+
+### ✅ ICU-compatible syntax
+
+Supports a **limited subset of ICU MessageFormat**, sufficient for CLI:
+
+- Interpolation: `{name}`, `{user.name}`, `{file-count}` (allowed: `a-z`, `A-Z`, `0-9`, `_`, `.`, `-`)
+- Plural: `{count, plural, one{...} few{...} other{...}}`
+- Offset: `offset:1`, `=0`, `#`
+
+⚠️ Not supported:
+- `select`, `selectordinal`, number/date formatting
+- Variables with spaces: `{first name}` → not replaced
+- Nested `plural` or `#` inside `=n`
+
+Implemented without external dependencies — only essentials.
+
+#### Example with `offset`
+
+```json
+"sockets.active": "{count, plural,
+  offset:1
+  =0 {Only server is on}
+  one {One more socket connected}
+  other {# more sockets connected}
+}"
+```
+
+- `count = 1` → `# = 0` → "Only server is on"
+- `count = 2` → `# = 1` → "One more socket connected"
+- `count = 5` → `# = 4` → "4 more sockets connected"
+
+Allows excluding persistent elements from the count.
+
+### ✅ Asynchronous initialization and caching
+
+- `initLocalizationAsync` loads and caches both fallback and system locale.
+- `setLocaleAsync` caches loaded locales — no redundant reloads.
+- Fallback chain: `current → fallback → {{key}}` if translation is missing.
+
+### ✅ Locale normalization
+
+The `setLocaleAsync` function accepts any string, but:
+- Automatically normalizes format (e.g. `ru_RU` → `ru-RU`)
+- Falls back to `fallbackLocale` on invalid input
+- Supports only `en-US` and `ru-RU`
+
+No manual locale validation required.
+
+### ✅ Language support
+
+- `ru`: full support for `one` / `few` / `many` (per [CLDR](https://cldr.unicode.org/))
+- `en` and others: `one` (if 1), otherwise `other`
+
+> For languages with special plural forms (e.g. `pl`, `ar`), extend `getPluralForm`.
+
+#### Language-specific behavior
+
+For Russian (`ru-RU`), fractional numbers (e.g. `36.6`) always use the `few` plural form (e.g. `36.6 градуса`), regardless of the integer part.
+
+This follows Russian grammatical rules: in mixed numbers, the fractional part governs the noun, requiring the genitive singular case (e.g. _"одна целая пять десятых градуса"_).
+
+Since ICU does not define a dedicated plural category for fractional numbers, `few` is used as the closest available match.
+
+## When to use?
+
+Use `@mirta/i18n` if:
+- Your tool supports multiple languages,
+- You need accurate plural forms (especially for Russian),
+- Locales are stored in `.json` and loaded asynchronously,
+- Small bundle size and zero dependencies are important.
+
+## Limitations
+
+- The `LocaleShape` type must be declared before use.
+- Localization instances are cached — avoid creating thousands of dynamic locales.
+- No support for `select`, `selectordinal`, number/date formatting.
+- Variables with spaces (`{first name}`) are not replaced.
+- `#` respects `offset` but does not support formatting.
+
+## Testing
+
+The package is covered with unit tests (`vitest`, `@mirta/testing`) verifying:
+- Initialization
+- Translation with variables and plural forms
+- Locale switching
+- Fallback logic

package/README.ru.md

@@ -0,0 +1,240 @@
+# @mirta/i18n
+
+[![en](https://img.shields.io/badge/lang-en-dimgray.svg?style=flat-square)](https://github.com/wb-mirta/core/blob/latest/packages/mirta-i18n/README.md)
+[![ru](https://img.shields.io/badge/lang-ru-olivedrab.svg?style=flat-square)](https://github.com/wb-mirta/core/blob/latest/packages/mirta-i18n/README.ru.md)
+[![NPM Version](https://img.shields.io/npm/v/@mirta/i18n?style=flat-square)](https://npmjs.com/package/@mirta/i18n)
+[![NPM Downloads](https://img.shields.io/npm/dm/@mirta/i18n?style=flat-square&logo=npm)](https://npmjs.com/package/@mirta/i18n)
+
+> Библиотека локализации для CLI-инструментов Mirta Framework, с ICU-совместимым синтаксисом.
+
+Пакет `@mirta/i18n` предназначен исключительно для **Node.js-инструментов** (≥ 20.6.0), не используется в рантайме Duktape.
+
+## Особенности
+
+- ✔️ Типобезопасность ключей и переменных — при определении `LocaleShape`
+- ✔️ ICU-совместимый синтаксис: `{var}`, `{count, plural, ...}`, `offset`, `=n`, `#`
+- ✔️ Асинхронная загрузка и кэширование `.json`
+- ✔️ Zero dependencies — только необходимый минимум
+- ✔️ Настраиваемый fallback (en-US по умолчанию)
+- ✔️ Контракт `t(key, vars)` — единый интерфейс перевода
+
+## 📦 Установка
+
+```sh
+pnpm add @mirta/i18n
+```
+
+⚠️ Этот пакет — часть внутренней инфраструктуры фреймворка Mirta. Обычно не используется напрямую.
+
+## Использование
+
+### 1. Подготовьте файлы локалей
+
+Организуйте папку `locales` следующим образом:
+
+```txt
+<пакет>/
+  locales/
+    en-US.json
+    ru-RU.json
+```
+Пример `en-US.json`:
+
+```json
+{
+  "title": "Welcome",
+  "files.plural": "{count, plural, =0{No files} one{One file} other{# files}}",
+  "greeting": "Hello, {name}!"
+}
+```
+
+### 2. Опишите LocaleShape
+
+Для включения типобезопасности определите интерфейс, совместимый с `GenericShape`:
+
+```ts
+interface LocaleShape {
+  messages: {
+    'title': string;
+    'files.plural': string;
+    'greeting': string;
+  };
+  variables: {
+    'files.plural': { count: number };
+    'greeting': { name: string };
+  };
+}
+```
+💡 Тип `LocaleShape` должен быть определён в проекте.  
+Mirta Framework использует внутренний скрипт генерации на основе `locales/en-US.json`.
+
+⚠️ При отсутствии `LocaleShape` используется `GenericShape` — типы ключей и переменных не проверяются.
+
+### 3. Инициализируйте локализацию
+
+В пакете, который подлежит локализации:
+
+```ts
+// src/i18n/index.ts
+import { initLocalizationAsync } from '@mirta/i18n'
+
+export const { t, setLocaleAsync } = await initLocalizationAsync<LocaleShape>()
+```
+
+### 4. Используйте перевод
+
+```ts
+console.log(t('title')) // → "Welcome"
+console.log(t('greeting', { name: 'Alice' })) // → "Hello, Alice!"
+console.log(t('files.plural', { count: 5 })) // → "5 files"
+```
+Смена локали:
+
+```ts
+await setLocaleAsync('ru-RU')
+console.log(t('title')) // → "Добро пожаловать"
+```
+
+## 📚 API
+
+### `initLocalizationAsync<TShape>(options)`
+
+Подготавливает подсистему локализации - загружает fallback-локаль, осуществляет попытку определения и установки системной локали.
+
+#### Параметры
+
+| Поле | Тип | Описание |
+|------|-----|----------|
+| `cwd` | `string` | Рабочая директория (по умолчанию: `process.cwd()`) |
+| `fallbackLocale` | `string` | Резервная локаль (по умолчанию: `'en-US'`) |
+
+#### Возвращает
+
+`Promise<Localization<TShape>>`
+
+#### Ошибки
+
+- `fallbackLoadFailed` — если не удалось загрузить fallback-локаль.
+
+---
+
+### `Localization<TShape>`
+
+| Метод | Тип | Описание |
+|------|-----|----------|
+| `t(key, vars?)` | `(key: K, vars?: VariablesOf<TShape, K>) => string` | Типобезопасный перевод |
+| `getLocale()` | `() => Locale` | Текущая локаль |
+| `setLocaleAsync(locale)` | `(locale: string) => Promise<void>` | Смена локали (нормализует и кэширует) |
+
+---
+
+### `Locale`
+
+Тип: `Branded<string, 'Locale'>` - брендированный тип локали.
+
+### `Lang`
+
+Тип: `Branded<string, 'Lang'>` - брендированный тип языка.
+
+## Ключевые возможности
+
+### ✅ Опциональная типобезопасность
+
+Функция `t()` обеспечивает типобезопасность **только при указании `LocaleShape`**:
+
+- Проверка существования ключей
+- Требование обязательных переменных
+- Запрет лишних полей
+
+```ts
+t('files.plural', { count: 2 }) // ✅
+t('files.plural', {})           // ❌ Ошибка: нет `count`
+t('title', { name: 'John' })    // ❌ Ошибка: `title` не принимает переменные
+```
+
+### ✅ ICU-совместимый синтаксис
+
+Поддерживает **ограниченный набор ICU MessageFormat**, достаточный для CLI:
+
+- Интерполяция: `{name}`, `{user.name}`, `{file-count}` (разрешены: `a-z`, `A-Z`, `0-9`, `_`, `.`, `-`)
+- Plural: `{count, plural, one{...} few{...} other{...}}`
+- Offset: `offset:1`, `=0`, `#`
+
+⚠️ Не поддерживает:
+- `select`, `selectordinal`, форматирование чисел/дат
+- Переменные с пробелами: `{first name}` → не заменяется
+- Вложенные `plural` или `#` внутри `=n`
+
+Реализовано без внешних зависимостей — только необходимый минимум.
+
+#### Пример с `offset`
+
+```json
+"sockets.active": "{count, plural,
+  offset:1
+  =0 {Только сервер включён}
+  one {Подключено ещё одно устройство}
+  other {Подключены ещё # устройства}
+}"
+```
+
+- `count = 1` → `# = 0` → "Только сервер включён"
+- `count = 2` → `# = 1` → "Подключено ещё одно устройство"
+- `count = 5` → `# = 4` → "Подключены ещё 4 устройства"
+
+Позволяет исключить постоянные элементы из счётчика.
+
+### ✅ Асинхронная инициализация и кэширование
+
+- `initLocalizationAsync` загружает и кэширует `fallbackLocale` и системную локаль.
+- `setLocaleAsync` кэширует уже загруженные локали — повторная загрузка не выполняется.
+- Fallback при отсутствии перевода: `current → fallback → {{key}}`.
+
+### ✅ Нормализация локалей
+
+Функция `setLocaleAsync` принимает любую строку, но:
+- Автоматически нормализует формат (например, `ru_RU` → `ru-RU`)
+- При некорректном значении — использует `fallbackLocale`
+- Поддерживает `en-US` и `ru-RU`
+
+Нет необходимости вручную валидировать локаль.
+
+### ✅ Поддержка языков
+
+- `ru`: полная поддержка `one` / `few` / `many` (по [CLDR](https://cldr.unicode.org/))
+- `en` и другие: `one` (если 1), иначе `other`
+
+> Для языков с особыми формами множественного числа (например, `pl`, `ar`) требуется расширение `getPluralForm`.
+
+#### Языковые особенности
+
+В русском языке (`ru-RU`) дробные числа всегда используют форму `few` (например, `36.6 градуса`), независимо от целой части.
+
+> При смешанном числе существительным управляет дробь, а не целое число.<br/>
+> — Д. Э. Розенталь. *Справочник по правописанию и литературной правке*, § 164, п. 8
+
+Форма `few` используется как ближайшая доступная в ICU, поскольку стандарт не предусматривает отдельной категории для дробных числительных.
+
+## Когда использовать?
+
+Используйте `@mirta/i18n`, если:
+- Инструмент требует поддержки нескольких языков,
+- Нужны точные формы множественного числа (особенно для русского),
+- Локали хранятся в `.json` и загружаются асинхронно,
+- Важны малый размер и отсутствие внешних зависимостей.
+
+## Ограничения
+
+- Тип `LocaleShape` должен быть объявлен до использования.
+- Наборы локалей кэшируются — избегайте создания тысяч динамических локалей.
+- Нет поддержки `select`, `selectordinal`, форматирования чисел и дат.
+- Переменные с пробелами (`{first name}`) — не заменяются.
+- Подстановка `#` учитывает `offset`, но не поддерживает форматирование.
+
+## Тестирование
+
+Пакет покрыт модульными тестами (`vitest`, `@mirta/testing`), проверяющими:
+- Инициализацию,
+- Перевод с переменными и plural,
+- Смену локали,
+- Fallback-логику.