@reformer/core 11.0.0-beta.6 → 11.0.0-beta.8

package/docs/llms/03-api-signatures.md

@@ -11,7 +11,7 @@ createModel<T extends object>(initial: T): FormModel<T>
 // model.arrayField         → ModelArray<Item>            (push/removeAt/insertAt/move/swap/clear/at/map/length)
 
 // Форма (ноды поверх сигналов модели)
-createForm<T>({ model, schema, behavior? }): FormProxy<T>
+createFormFromModel<T>({ model, schema, behavior? }): FormProxy<T>
 // form.<field>             → FieldNode / GroupNode / FormArrayProxy
 // form.<field>.setValue(v) / .value.value / .errors.value / .disabled.value
 // form.<field>.enable() / .disable() / .reset() / .markAsTouched() / .setErrors([...])
@@ -57,11 +57,17 @@ minAge(years: number, options?: { message?: string })
 maxAge(years: number, options?: { message?: string })
 ```
 
+Кроме `message`, каждое правило принимает `messageKey` (ключ словаря приложения) и `params`.
+Без `message` правило кладёт в ошибку пустую строку, а текст при отображении берётся из словаря
+локали по коду (`validation.<code>`): «Обязательное поле» под русской локалью, английская фраза без
+провайдера. Явное `message` важнее словаря, но языком не переключается; для локализуемого текста —
+`messageKey`. Подробно — [34-i18n.md](./34-i18n.md).
+
 Использование: layout-дерево `createForm` привязывает поля к сигналам, правила живут отдельной
 `ValidationSchema` и гоняются раннером `validateModel` по требованию.
 
 ```typescript
-import { createModel, createForm } from '@reformer/core';
+import { createModel, createForm, createFormFromModel } from '@reformer/core';
 import { defineValidationSchema, validate, validateModel } from '@reformer/core/validation';
 import { required, min, max, email } from '@reformer/core/validators';
 
@@ -69,7 +75,7 @@ type Loan = { email: string; age: number | null; amount: number | null };
 const model = createModel<Loan>({ email: '', age: null, amount: null });
 
 // layout-схема createForm НЕ несёт validators — только привязка поля к сигналу + компонент
-const form = createForm({
+const form = createFormFromModel({
   model,
   schema: {
     email:  { value: model.$.email,  component: Input },
@@ -256,7 +262,7 @@ const behavior = defineFormBehavior<MyForm>(({ model, form }) => {
   });
 });
 
-const form = createForm({ model, schema, behavior });
+const form = createFormFromModel({ model, schema, behavior });
 ```
 
 DSL-операторы: `compute` (auto-tracking, без явного списка источников), `computeFrom`, `copyFrom`,

package/docs/llms/09-formschema.md

@@ -25,7 +25,7 @@ layout-схеме НЕТ — правила живут в отдельной с
 ### Primitive Fields
 
 ```typescript
-import { createModel, createForm } from '@reformer/core';
+import { createModel, createFormFromModel } from '@reformer/core';
 import { defineValidationSchema, validate } from '@reformer/core/validation';
 import { required } from '@reformer/core/validators';
 import { Input, InputNumber, SelectAsync, CheckboxWithLabel } from '@reformer/ui-kit';
@@ -66,7 +66,7 @@ const schema = {
   },
 };
 
-const form = createForm<MyForm>({ model, schema });
+const form = createFormFromModel<MyForm>({ model, schema });
 ```
 
 ### Nested Objects
@@ -111,7 +111,7 @@ const schema = {
 
 ```typescript
 // M1: данные из модели + схема (+ опциональный декларативный behavior)
-const form = createForm<MyForm>({
+const form = createFormFromModel<MyForm>({
   model,                 // FormModel<MyForm> — обязателен
   schema,                // дерево узлов, привязанных к сигналам
   behavior: myBehavior,  // опционально: defineFormBehavior(...) из @reformer/core/behaviors
@@ -126,12 +126,12 @@ model.items.push({ id: '1', name: 'Item' }); // операции над масс
 > **Тип `schema` в M1 — `unknown`, не `FormSchema<T>`.** Это осознанно: интерпретатор обходит
 > произвольную структуру и собирает листья `{ value: signal, component?, ... }`, поэтому обёртки
 > (`{ children: [...] }`, wizard/steps) компилируются. Строгий `FormSchema<T>` (keyed-map по полям
-> `T`) применяется только на legacy-пути `createForm(schema)` без модели.
+> `T`) применяется только на legacy-пути `createLegacyForm(schema)` без модели.
 
 ### createForm Returns a Proxy
 
 ```typescript
-const form = createForm<MyForm>({ model, schema });
+const form = createFormFromModel<MyForm>({ model, schema });
 
 form.email;          // FieldNode<string> — TypeScript знает тип
 form.address.city;   // FieldNode<string> — вложенный доступ

package/docs/llms/10-arrays.md

@@ -6,7 +6,7 @@
 элемента из его под-модели (`FormModel<Item>`).
 
 ```typescript
-import { createModel, createForm, type FormModel } from '@reformer/core';
+import { createModel, createFormFromModel, type FormModel } from '@reformer/core';
 import { Input, InputNumber } from '@reformer/ui-kit';
 
 type Item = { id: string; name: string; price: number };
@@ -25,13 +25,62 @@ const schema = {
   items: { array: model.items, item: itemSchema },
 };
 
-const form = createForm<MyForm>({ model, schema });
+const form = createFormFromModel<MyForm>({ model, schema });
 ```
 
 > **Type constraint:** тип элемента `Item` объявляй через `type`-alias (не `interface`) — иначе
 > он не совместим с `Record<string, FormValue>` и `ArrayNode<Item>` его отвергнет.
 > См. `30-type-safety-recipes.md`.
 
+### Массив как ОДНО значение поля
+
+Массив бывает не набором под-форм, а одним значением: мультивыбор, теги, список файлов. Чем он
+является, решает **схема**, а не данные: `{ array, item }` — набор под-форм, а узел поля
+`{ value: model.$.<путь>, component }` — одно значение. Массив, к которому в схеме ничего не
+привязано, в форму не попадает.
+
+```typescript
+type MyForm = { tags: string[] };
+
+const model = createModel<MyForm>({ tags: [] });
+
+const schema = {
+  tags: { value: model.$.tags, component: SelectMulti }, // поле над массивом целиком
+};
+const form = createFormFromModel<MyForm>({ model, schema });
+
+form.tags.setValue(['a', 'b']); // FieldNode<string[]>
+model.$.tags.value = ['c']; // ручка значения: заменяет массив целиком
+validate(model.$.tags, [required(), maxLength(3)]); // правило получает массив
+```
+
+- `model.$.<массив>` — записываемая ручка значения (`PathAwareSignal`): подходит для `value:` в
+  схеме, `validate`/`cross`, `enableWhen`/`copyFrom` и для `model.signalAt(path)`.
+- Узел-массив хранит только массив: запись `null`/`undefined` даёт `[]`. Нужно отличать «не
+  выбирали» от «выбрали ничего» — объявляй поле `T[] | null` с начальным `null`: в рантайме это
+  лист, и привязывается он так же.
+- Запись в узел-ГРУППУ (`model.$.<группа>.value = …`) — ошибка: группа пишется по полям или через
+  `model.patch(...)`.
+
+### Массив в группе и в строке другого массива
+
+Узел `{ array, item }` стоит на любой глубине: массив в группе получает ноду `form.<группа>.<массив>`,
+массив в строке — `form.<массив>.at(i).<массив>`. Под-схема строки объявляет свои массивы так же.
+
+```typescript
+const contactItem = (contact: FormModel<Contact>) => ({
+  name: { value: contact.$.name, component: Input },
+  phones: { array: contact.phones, item: phoneItem }, // массив в строке массива
+});
+
+const schema = {
+  hotlines: { array: model.details.hotlines, item: phoneItem }, // массив в группе
+  contacts: { array: model.contacts, item: contactItem },
+};
+```
+
+Поведение строк вложенного массива — `applyEach` внутри схемы строки, см. `21-array-operations.md`.
+
 ### Один массив — три слоя (три разных движка)
 
 Одна и та же коллекция описывается **тремя разными формами** — по одной на движок. Их легко
@@ -43,7 +92,7 @@ const form = createForm<MyForm>({ model, schema });
    `model.$.properties`.
 
    ```typescript
-   // узел схемы для createForm({ model, schema })
+   // узел схемы для createFormFromModel({ model, schema })
    properties: { array: model.properties, item: propertyItem },
    ```
 

package/docs/llms/16-ui-components.md

@@ -19,7 +19,7 @@
 
 ```tsx
 import { useMemo } from 'react';
-import { createModel, createForm } from '@reformer/core';
+import { createModel, createFormFromModel } from '@reformer/core';
 import { FormField, Input, SelectAsync, CheckboxWithLabel, Button } from '@reformer/ui-kit';
 
 type RegistrationForm = {
@@ -54,7 +54,7 @@ function RegistrationPage() {
         componentProps: { label: 'I agree to terms' },
       },
     };
-    return createForm<RegistrationForm>({ model, schema });
+    return createFormFromModel<RegistrationForm>({ model, schema });
   }, []);
 
   return (

package/docs/llms/18-conditional-fields.md

@@ -56,7 +56,7 @@ export const creditBehavior = defineFormBehavior<CreditForm>(({ model }) => {
 - **Все поля должны быть материализованы в модели** (`createModel`), даже те, что показываются
   только под условием. `enableWhen`/`compute`/`copyFrom` принимают сигналы `model.$.field`, а не
   строковые пути; сигнала для несуществующего поля нет.
-- Поведение подключается к форме через `createForm({ model, schema, behavior })` — форма владеет
+- Поведение подключается к форме через `createFormFromModel({ model, schema, behavior })` — форма владеет
   жизненным циклом, DSL-операторы регистрируют свой cleanup сами (ручной массив cleanup'ов не нужен).
 - Таргетом может быть и **группа**: `enableWhen(model.$.residenceAddress, () => model.sameAsRegistration === false)`
   проходит по поддереву; без `resetOnDisable` значение группы сохраняется (удобно, когда оно копируется

package/docs/llms/21-array-operations.md

@@ -76,6 +76,32 @@ const behavior = defineFormBehavior<MyForm>(({ model }) => {
 });
 ```
 
+### Вложенные области — массив в группе и в строке массива
+
+Узел `{ array, item }` и операторы `applyEach` / `apply` / `enableWhen` работают на любой глубине:
+цель оператора — **ручка** `model.$.…`, под-модель и нода находятся по её идентичности, а не по
+пути.
+
+```typescript
+const phoneBehavior = defineFormBehavior<Phone>(({ model: phone }) => {
+  enableWhen(phone.$.number, () => phone.primary);
+});
+
+const contactBehavior = defineFormBehavior<Contact>(({ model: contact }) => {
+  applyEach(contact.$.phones, phoneBehavior); // массив внутри строки
+  enableWhen(contact.$.address, () => contact.quantity > 0); // группа внутри строки
+  apply(contact.$.address, addressBehavior); // под-схема получает настоящую под-модель
+});
+
+const behavior = defineFormBehavior<MyForm>(({ model }) => {
+  applyEach(model.$.contacts, contactBehavior);
+});
+```
+
+Ручка → value-фасад: `modelOf(model.$.address)` — под-модель (`get` / `set` / `patch`),
+`modelOf(model.$.phones)` — фасад массива (`push` / `removeAt` / `at`). Нода формы по ручке —
+`getNodeForSignal(model.$.address)`.
+
 ### Aggregate write — aggregateInto
 
 Агрегатная запись в строки (например, «последняя строка = 100 − Σ остальных»):

package/docs/llms/28-submit-and-reset.md

@@ -48,7 +48,7 @@ form.<field>.clearErrors();
 
 ```tsx
 import { useMemo } from 'react';
-import { createModel, createForm } from '@reformer/core';
+import { createModel, createForm, createFormFromModel } from '@reformer/core';
 import { defineValidationSchema, validate, validateModel } from '@reformer/core/validation';
 import { required, email, minLength } from '@reformer/core/validators';
 
@@ -66,7 +66,7 @@ function RegistrationForm() {
   const { model, form } = useMemo(() => {
     const m = createModel<RegistrationFormData>({ username: '', email: '', password: '' });
     // schema здесь — layout-дерево нод (компоненты/раскладка), без валидаторов.
-    return { model: m, form: createForm({ model: m, schema: buildLayout(m) }) };
+    return { model: m, form: createFormFromModel({ model: m, schema: buildLayout(m) }) };
   }, []);
 
   const handleSubmit = async (e: React.FormEvent) => {
@@ -198,7 +198,7 @@ const handleSubmit = async (e) => {
 
 ```typescript
 // ❌ Валидаторы в layout-дереве, отдаваемом в createForm — layout не несёт правил
-createForm({ model, schema: { username: { value: '', validators: [required()] } } });
+createFormFromModel({ model, schema: { username: { value: '', validators: [required()] } } });
 
 // ✅ Валидация — отдельная схема, прогоняется раннером
 const schema = defineValidationSchema<T>(({ model }) => {

package/docs/llms/29-async-preload.md

@@ -30,7 +30,7 @@ Initial values задаются в `createModel(initial)`; `reset()` возвр
 ### Initial values в модели
 
 ```typescript
-import { createModel, createForm } from '@reformer/core';
+import { createModel, createFormFromModel } from '@reformer/core';
 import { Input, SelectAsync, CheckboxWithLabel } from '@reformer/ui-kit';
 
 type ProfileForm = { username: string; language: 'ru' | 'en'; marketing: boolean };
@@ -51,7 +51,7 @@ const schema = {
   },
   marketing: { value: model.$.marketing, component: CheckboxWithLabel, componentProps: { label: 'Рассылка' } },
 };
-const form = createForm({ model, schema });
+const form = createFormFromModel({ model, schema });
 // model.get() === { username: '', language: 'ru', marketing: true }
 // после правок: model.reset() возвращает к этим значениям
 ```
@@ -138,14 +138,14 @@ export const addressBehavior = defineFormBehavior<AddressForm>(({ model, form })
 // ❌ model/form пересоздаются на каждый рендер → preload запускается каждый раз
 function MyForm() {
   const model = createModel<T>(initial);   // КАЖДЫЙ рендер!
-  const form = createForm({ model, schema });
+  const form = createFormFromModel({ model, schema });
 }
 
 // ✅ Стабильные ссылки через useMemo
 function MyForm() {
   const { model, form } = useMemo(() => {
     const m = createModel<T>(initial);
-    return { model: m, form: createForm({ model: m, schema: buildSchema(m) }) };
+    return { model: m, form: createFormFromModel({ model: m, schema: buildSchema(m) }) };
   }, []);
 }
 ```

package/docs/llms/33-validation-strategy.md

@@ -72,7 +72,7 @@ function createFormValidation<T>(
 `markAsTouched` не нужен.
 
 ```tsx
-import { createModel, createForm, useFormValidation } from '@reformer/core';
+import { createModel, createFormFromModel, useFormValidation } from '@reformer/core';
 import { defineValidationSchema, validate } from '@reformer/core/validation';
 import { required, email, minLength } from '@reformer/core/validators';
 
@@ -87,7 +87,7 @@ const registrationValidation = defineValidationSchema<RegistrationData>(({ model
 
 function RegistrationForm() {
   const model = useMemo(() => createModel<RegistrationData>({ username: '', email: '', password: '' }), []);
-  const form = useMemo(() => createForm({ model }), [model]);
+  const form = useMemo(() => createFormFromModel({ model }), [model]);
 
   const { submit, isValidating } = useFormValidation({
     model,

package/docs/llms/34-i18n.md

@@ -0,0 +1,272 @@
+# i18n — локаль, загрузка словарей и провайдер
+
+## Purpose
+
+Подпуть `@reformer/core/i18n` — общий рантайм локализации для всех пакетов `@reformer/*`: объект
+локали, загрузка словарей, React-провайдер, перевод и форматирование. Язык задаётся провайдером,
+подгружается динамически и переключается на лету; узлы формы при этом не пересоздаются.
+
+Без провайдера всё работает на английском: у каждого пакета есть встроенная английская таблица.
+
+> Импорт всегда из `@reformer/core/i18n`. Из главной бочки `@reformer/core` этот модуль не
+> реэкспортируется: React-контекст локализации обязан существовать в одном экземпляре.
+
+## Локаль — это данные
+
+```typescript
+interface FormLocale {
+  code: string; // BCP 47: 'en', 'ru', 'pt-BR' — по нему работают Intl и plural
+  messages: Record<string, string>; // плоский словарь: ключ → сообщение ICU
+  weekStartsOn?: 0 | 1 | 2 | 3 | 4 | 5 | 6;
+  dateLocale?: unknown; // необязательно: объект локали react-day-picker / date-fns
+  dateFormat?: string; // необязательно: токены date-fns для DatePicker
+}
+```
+
+Функций в локали нет, поэтому её можно положить JSON-файлом на сервер и получить по сети:
+
+```json
+{ "code": "ru", "weekStartsOn": 1, "messages": { "profile.title": "Профиль" } }
+```
+
+`extendLocale(base, patch)` возвращает новую локаль: словари сливаются (ключи из `patch` важнее),
+остальные поля заменяются.
+
+## Формат сообщений — подмножество ICU
+
+| Конструкция         | Пример                                                                    |
+| ------------------- | ------------------------------------------------------------------------- |
+| подстановка         | `Открыт файл {name}`                                                      |
+| множественные формы | `{count, plural, one{# файл} few{# файла} many{# файлов} other{# файла}}` |
+| точное значение     | `{count, plural, =0{файлов нет} other{# файлов}}`                         |
+| выбор               | `{gender, select, male{он} female{она} other{оно}}`                       |
+| экранирование       | `'{'` → `{`, `'}'` → `}`, `''` → `'`                                      |
+
+- Ветка `other` обязательна. `#` внутри `plural` — число, отформатированное по языку.
+- Типы `number`, `date`, `time`, `selectordinal` не поддерживаются: числа и даты форматируйте
+  отдельно (`useI18n().number`, `.date`) и передавайте готовой строкой.
+- Категории (`one`/`few`/`many`) берутся из `Intl.PluralRules` языка локали.
+
+## Загрузка локалей
+
+Откуда брать словарь, решает приложение: источник — функция `(code) => локаль | словарь`.
+
+```typescript
+import { createLocaleLoader, fetchMessages } from '@reformer/core/i18n';
+import { loadCoreLocale } from '@reformer/core/locale';
+
+export const loadLocale = createLocaleLoader([
+  loadCoreLocale, // встроенные словари ядра — чанк нужного языка
+  fetchMessages((code) => `/locales/${code}.json`), // ключи приложения и правки — с сервера
+]);
+```
+
+- Источники опрашиваются параллельно, сливаются по порядку: поздний перекрывает ранний.
+- Источник отдаёт локаль целиком (`{ code, messages, … }`) или голый словарь (`{ "a.b": "…" }`);
+  `null` означает «для этого языка у меня ничего нет» и ошибкой не считается.
+- Результат кэшируется по коду языка, идущий запрос не дублируется.
+- Отказ любого источника — отказ загрузки. Источник, которому можно промахнуться, оборачивайте:
+  `(code) => source(code).catch(() => null)`.
+- `loadLocale.peek(code)` — уже загруженная локаль или `undefined`; `loadLocale.preload(code)` — то
+  же, что вызов загрузчика.
+
+Ядро отдаёт свои локали в трёх видах:
+
+| Вид               | Импорт                                      | Для чего                                        |
+| ----------------- | ------------------------------------------- | ----------------------------------------------- |
+| загрузчик         | `loadCoreLocale` из `@reformer/core/locale` | основной путь: чанк языка по запросу            |
+| JSON-файл         | `@reformer/core/locale/ru.json`             | выложить на свой сервер, править без пересборки |
+| синхронный модуль | `ru` из `@reformer/core/locale/ru`          | SSR и тесты                                     |
+
+Встроенные языки ядра — `en` и `ru`. Словарь ядра несёт тексты ошибок валидации
+(`validation.<code>`) и единицы размера файла (`format.fileSize.b|kb|mb|gb|tb`).
+
+Пакеты выше отдают локаль накопительно и в тех же трёх видах, поэтому источник встроенных словарей
+в загрузчике всегда один — самого верхнего из используемых пакетов:
+
+| Пакеты приложения               | Источник                                     | Что в локали                      |
+| ------------------------------- | -------------------------------------------- | --------------------------------- |
+| только ядро                     | `loadCoreLocale` из `@reformer/core/locale`  | ошибки валидации, размер файла    |
+| ядро + `@reformer/cdk`          | `loadCdkLocale` из `@reformer/cdk/locale`    | то же плюс строки cdk (`cdk.*`)   |
+| ядро + cdk + `@reformer/ui-kit` | `loadKitLocale` из `@reformer/ui-kit/locale` | то же плюс подписи кита (`kit.*`) |
+
+## Провайдер
+
+```tsx
+import { I18nProvider } from '@reformer/core/i18n';
+
+function App() {
+  const [lang, setLang] = useState('ru');
+  return (
+    <I18nProvider lang={lang} load={loadLocale}>
+      <LangSwitch value={lang} onChange={setLang} />
+      <CreditForm />
+    </I18nProvider>
+  );
+}
+```
+
+| Проп            | Назначение                                                               |
+| --------------- | ------------------------------------------------------------------------ |
+| `lang` + `load` | провайдер грузит локаль сам                                              |
+| `fallback`      | что показать, пока не загружена самая первая локаль; по умолчанию ничего |
+| `onError`       | отказ загрузки `(error, lang)`                                           |
+| `locale`        | готовый объект вместо `lang` + `load` — SSR, тесты                       |
+
+Поведение при `lang` + `load`:
+
+- при смене `lang` на экране остаётся прежний язык, пока новый не загрузится;
+  `useI18n().pending` — для индикатора;
+- при быстром переключении применяется только последний запрос;
+- ошибка загрузки язык не меняет и попадает в `useI18n().error` и `onError`;
+- если локаль уже в кэше (`await loadLocale.preload(lang)` до монтирования), первый рендер
+  синхронный и `fallback` не показывается.
+
+SSR: эффекты на сервере не выполняются, поэтому там передавайте готовый объект —
+`<I18nProvider locale={ru}>` — либо заранее вызовите `preload`.
+
+Вложенный провайдер заменяет локаль для своего поддерева целиком.
+
+## Хуки
+
+```typescript
+const { code, locale, pending, error, t, has, number, date, fileSize } = useI18n();
+
+t('profile.title'); // ключ приложения
+t('cart.items', { count: 3 }); // с подстановками
+t('cart.empty', undefined, 'Your cart is empty'); // английский текст на случай промаха
+number(1234.5); // '1 234,5' в ru
+date(new Date(), { dateStyle: 'long' }); // '15 января 2024 г.' в ru
+fileSize(1536); // '1,5 КБ' в ru, '1.5 KB' без провайдера
+```
+
+`useMessages(builtinEn)` — для авторов пакетов и китов: ищет ключ в локали провайдера, а при
+промахе берёт встроенную английскую таблицу пакета. Тип ключа выводится из таблицы.
+
+```tsx
+import en from './locale/en.json';
+
+function ClearButton() {
+  const t = useMessages(en);
+  return <button aria-label={t('kit.select.clear')} />;
+}
+```
+
+## Тексты ошибок валидации
+
+Правила из `@reformer/core/validators` несут только `code` и `params`; готового текста у них нет
+(`message` по умолчанию — пустая строка). Строку даёт резолвер при отображении ошибки:
+
+1. `messageKey` автора правила — если такой ключ есть в активной локали;
+2. явное `message` автора правила;
+3. `validation.<code>` из словаря локали;
+4. `validation.<code>` из встроенной английской таблицы ядра;
+5. сам код — для своих кодов, которых нет ни в одном словаре.
+
+```typescript
+validate(model.$.email, [
+  required(), // «Обязательное поле» в ru, английская фраза без провайдера
+  minLength(5, { message: 'Слишком коротко' }), // явный текст: важнее словаря, но языком не переключается
+  email({ messageKey: 'profile.email.invalid' }), // ключ словаря приложения: переключается вместе с языком
+]);
+```
+
+- Текст получается при отображении, а не при проверке: смена языка переводит уже показанные
+  ошибки без повторной валидации.
+- `FormField` (`@reformer/cdk`, `@reformer/ui-kit`) резолвит ошибку сам. В своём компоненте —
+  `useValidationMessage()`; вне React — `resolveValidationError(error, createI18n(locale))`.
+- Свой код ошибки локализуется ключом `validation.<свой_код>` в словаре приложения либо
+  `messageKey` в самом правиле.
+- Встроенный текст меняется тем же ключом в словаре приложения:
+  `extendLocale(ru, { messages: { 'validation.required': 'Заполните поле' } })`.
+- Параметры готовятся до подстановки: `Date` — по языку (`15 янв. 2030 г.`), массив — перечнем,
+  размеры в байтах (`maxFileSize`, `minFileSize`, `actualSize`, `maxTotalFileSize`, `actualTotal`) —
+  строкой с единицей (`5 МБ`). Числа остаются числами, поэтому в сообщении работает `plural`.
+
+```tsx
+function FieldErrors({ control }: { control: FieldNode<string> }) {
+  const message = useValidationMessage();
+  const { errors, shouldShowError } = useFormControl(control);
+  return shouldShowError ? <span role="alert">{message(errors[0])}</span> : null;
+}
+```
+
+Смонтированный `ValidationMessagesProvider` из `@reformer/cdk` заменяет этот резолвер целиком:
+локаль для ошибок в его поддереве не участвует.
+
+## Что показывается, когда ключа нет
+
+| Ключ                       | Нет в локали                                                    | Сообщение не разбирается                              |
+| -------------------------- | --------------------------------------------------------------- | ----------------------------------------------------- |
+| пакета (`useMessages`)     | встроенный английский пакета                                    | встроенный английский, `console.error` вне production |
+| приложения (`useI18n().t`) | `defaultMessage`, затем сам ключ; `console.warn` вне production | то же, `console.error`                                |
+
+Пропущенная подстановка выводится как `{name}`. Форма не падает ни в одном из случаев: неполный
+словарь, пришедший по сети, — законный сценарий.
+
+## Проверка словаря в тестах
+
+```typescript
+import { validateLocale } from '@reformer/core/i18n';
+
+expect(validateLocale(ruJson, enJson)).toEqual([]);
+// находит: syntax (не разбирается), missing / extra (ключи), arguments (потерянная подстановка)
+```
+
+## Описатели сообщений (низкий уровень)
+
+`msg(key, values?, defaultMessage?)` создаёт описатель сообщения, `defineMessages(appEn)` — `msg` с
+типизированными ключами, `resolveLocalized(value, i18n)` раскрывает описатели в объекте пропсов.
+
+> ⚠️ Рендереры и `FormField` описатели сами пока НЕ раскрывают. Не кладите `msg(...)` в
+> `componentProps` схемы: компонент получит объект вместо строки. До появления раскрытия в
+> рендерерах вызывайте `resolveLocalized` вручную или используйте `useI18n().t`.
+
+## Anti-patterns
+
+```typescript
+// ❌ Импорт из главной бочки — i18n там нет, а второй путь импорта дал бы вторую копию контекста
+import { I18nProvider } from '@reformer/core';
+
+// ✅ Единственный путь импорта — подпуть i18n
+import { I18nProvider } from '@reformer/core/i18n';
+```
+
+```tsx
+// ❌ Новый загрузчик на каждый рендер: кэш теряется, локаль грузится заново, первый кадр — fallback
+<I18nProvider lang={lang} load={createLocaleLoader([loadCoreLocale])}>
+
+// ✅ Загрузчик — константа модуля: один кэш на приложение
+const loadLocale = createLocaleLoader([loadCoreLocale]);
+<I18nProvider lang={lang} load={loadLocale}>
+```
+
+```typescript
+// ❌ Число или дата типами ICU внутри сообщения — не поддерживается, сообщение не разберётся
+const message = 'Итого: {total, number}';
+
+// ✅ Отформатировать отдельно и передать готовой строкой
+t('cart.total', { total: number(total, { style: 'currency', currency: 'RUB' }) });
+```
+
+```tsx
+// ❌ Ошибка выводится полем message: у правил без своего текста оно пустое — на экране ничего
+<span>{errors[0].message}</span>;
+
+// ✅ Текст ошибки — через резолвер: он знает словарь локали, messageKey и явное сообщение
+const message = useValidationMessage();
+<span>{message(errors[0])}</span>;
+```
+
+```typescript
+// ❌ Настройки локали без словаря: объект без поля messages принимается за словарь сообщений
+const source = () => ({ weekStartsOn: 1 });
+
+// ✅ Часть локали узнаётся по полю messages — отдавайте его хотя бы пустым
+const source = () => ({ weekStartsOn: 1, messages: {} });
+```
+
+## See also
+
+- [28-submit-and-reset.md](./28-submit-and-reset.md) — жизненный цикл формы; смена языка его не затрагивает
+- [33-validation-strategy.md](./33-validation-strategy.md) — когда запускается валидация