@reformer/core 11.0.0-beta.5 → 11.0.0-beta.7

package/llms.txt

@@ -38,6 +38,7 @@
 - 31-async-validator-debounce.md — async-validator-debounce
 - 32-async-options-loading.md — async-options-loading
 - 33-validation-strategy.md — useFormValidation — Единый выбор стратегии валидации
+- 34-i18n.md — i18n — локаль, загрузка словарей и провайдер
 - API Reference (auto-generated from JSDoc)
 
 ## 1. 1. API Reference
@@ -128,7 +129,7 @@ const { value, errors, disabled } = useFormControl(control.loanType);
 import { createCoreForm, createModel, useFormBundle, type FormProxy } from '@reformer/core';
 import { defineValidationSchema, validate, validateModel } from '@reformer/core/validation';
 import { required, email } from '@reformer/core/validators';
-import { FormField, InputField, Button } from '@reformer/ui-kit';
+import { FormField, Input, Button } from '@reformer/ui-kit';
 
 // 1. Define form type as `type` alias (not `interface` — see Recipe 2)
 type ContactForm = {
@@ -144,12 +145,12 @@ const model = createModel<ContactForm>({ name: '', email: '' });
 const schema = {
   name: {
     value: model.$.name,
-    component: InputField,
+    component: Input,
     componentProps: { label: 'Name', placeholder: 'Your name' },
   },
   email: {
     value: model.$.email,
-    component: InputField,
+    component: Input,
     componentProps: { label: 'Email', type: 'email' },
   },
 };
@@ -223,14 +224,14 @@ const model = createModel<MyForm>({ properties: [] });
 const propertyItem = (item: FormModel<PropertyItem>) => ({
   type: {
     value: item.$.type,
-    component: SelectField,
+    component: SelectAsync,
     componentProps: { label: 'Тип', options: [/* ... */] },
   },
-  description: { value: item.$.description, component: TextareaField, componentProps: { label: 'Описание' } },
+  description: { value: item.$.description, component: Textarea, componentProps: { label: 'Описание' } },
   estimatedValue: {
     value: item.$.estimatedValue,
-    component: InputField,
-    componentProps: { label: 'Стоимость', type: 'number' },
+    component: InputNumber,
+    componentProps: { label: 'Стоимость' },
   },
 });
 
@@ -320,6 +321,12 @@ 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` по требованию.
 
@@ -328,16 +335,16 @@ import { createModel, createForm } from '@reformer/core';
 import { defineValidationSchema, validate, validateModel } from '@reformer/core/validation';
 import { required, min, max, email } from '@reformer/core/validators';
 
-type Loan = { email: string; age: number; amount: number };
-const model = createModel<Loan>({ email: '', age: 0, amount: 0 });
+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({
   model,
   schema: {
-    email:  { value: model.$.email,  component: InputField },
-    age:    { value: model.$.age,    component: InputField },
-    amount: { value: model.$.amount, component: InputField },
+    email:  { value: model.$.email,  component: Input },
+    age:    { value: model.$.age,    component: InputNumber },
+    amount: { value: model.$.amount, component: InputNumber },
   },
 });
 
@@ -837,7 +844,7 @@ computeFrom([model.$.price, model.$.quantity], model.$.total, (price, qty) => pr
 ```typescript
 // ❌ WRONG - дерево { value, validators } и позиционная строка удалены
 const schema = {
-  email: { value: model.$.email, component: InputField, validators: [required(), email()] },
+  email: { value: model.$.email, component: Input, validators: [required(), email()] },
 };
 validate(path.email, required(), 'Email is required'); // старая сигнатура validate() — удалена
 
@@ -1090,7 +1097,7 @@ layout-схеме НЕТ — правила живут в отдельной с
 ```typescript
 {
   value: model.$.fieldName,   // сигнал модели (PathAwareSignal) — обязателен
-  component: InputField,           // React-компонент
+  component: Input,           // React-компонент
   componentProps?: object,    // пропсы (label, placeholder, options, type, ...)
   disabled?: boolean,
   updateOn?: 'change' | 'blur' | 'submit',
@@ -1108,7 +1115,7 @@ layout-схеме НЕТ — правила живут в отдельной с
 import { createModel, createForm } from '@reformer/core';
 import { defineValidationSchema, validate } from '@reformer/core/validation';
 import { required } from '@reformer/core/validators';
-import { InputField, SelectField, CheckboxField } from '@reformer/ui-kit';
+import { Input, InputNumber, SelectAsync, CheckboxWithLabel } from '@reformer/ui-kit';
 
 const model = createModel<MyForm>({ name: '', age: null, agree: false, status: 'active' });
 
@@ -1120,22 +1127,22 @@ const myValidation = defineValidationSchema<MyForm>(({ model }) => {
 const schema = {
   name: {
     value: model.$.name,
-    component: InputField,
+    component: Input,
     componentProps: { label: 'Name', placeholder: 'Enter name' },
   },
   age: {
     value: model.$.age,
-    component: InputField,
-    componentProps: { type: 'number', label: 'Age' },
+    component: InputNumber,
+    componentProps: { label: 'Age' },
   },
   agree: {
     value: model.$.agree,
-    component: CheckboxField,
+    component: CheckboxWithLabel,
     componentProps: { label: 'I agree to terms' },
   },
   status: {
     value: model.$.status,
-    component: SelectField,
+    component: SelectAsync,
     componentProps: {
       label: 'Status',
       options: [
@@ -1159,9 +1166,9 @@ const form = createForm<MyForm>({ model, schema });
 import type { FormModel } from '@reformer/core';
 
 const addressNodes = (m: FormModel<Address>) => ({
-  street: { value: m.$.street, component: InputField, componentProps: { label: 'Street' } },
-  city:   { value: m.$.city,   component: InputField, componentProps: { label: 'City' } },
-  zip:    { value: m.$.zip,    component: InputField, componentProps: { label: 'ZIP' } },
+  street: { value: m.$.street, component: Input, componentProps: { label: 'Street' } },
+  city:   { value: m.$.city,   component: Input, componentProps: { label: 'City' } },
+  zip:    { value: m.$.zip,    component: Input, componentProps: { label: 'ZIP' } },
 });
 
 const schema = {
@@ -1178,8 +1185,8 @@ const schema = {
 import type { FormModel } from '@reformer/core';
 
 const itemSchema = (item: FormModel<Item>) => ({
-  id:   { value: item.$.id,   component: InputField, componentProps: { label: 'ID' } },
-  name: { value: item.$.name, component: InputField, componentProps: { label: 'Name' } },
+  id:   { value: item.$.id,   component: Input, componentProps: { label: 'ID' } },
+  name: { value: item.$.name, component: Input, componentProps: { label: 'Name' } },
 });
 
 const schema = {
@@ -1233,7 +1240,7 @@ if (isFieldNode(node)) { /* ... */ }
 
 ```typescript
 import { createModel, createForm, type FormModel } from '@reformer/core';
-import { InputField } from '@reformer/ui-kit';
+import { Input, InputNumber } from '@reformer/ui-kit';
 
 type Item = { id: string; name: string; price: number };
 type MyForm = { items: Item[] };
@@ -1242,9 +1249,9 @@ const model = createModel<MyForm>({ items: [] });
 
 // под-схема одного элемента (item.$.field — сигнал под-модели)
 const itemSchema = (item: FormModel<Item>) => ({
-  id:    { value: item.$.id,    component: InputField },
-  name:  { value: item.$.name,  component: InputField },
-  price: { value: item.$.price, component: InputField, componentProps: { type: 'number' } },
+  id:    { value: item.$.id,    component: Input },
+  name:  { value: item.$.name,  component: Input },
+  price: { value: item.$.price, component: InputNumber },
 });
 
 const schema = {
@@ -1258,6 +1265,36 @@ const form = createForm<MyForm>({ model, schema });
 > он не совместим с `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 = createForm<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(...)`.
+
 ### Один массив — три слоя (три разных движка)
 
 Одна и та же коллекция описывается **тремя разными формами** — по одной на движок. Их легко
@@ -1645,7 +1682,7 @@ import { revalidateWhen, type ValidationError } from '@reformer/core';
 // ❌ старое (УДАЛЕНО): дерево { value, validators }, ModelValidator (value, scope, root), validateFormModel
 const legacyRule: ModelValidator<number, unknown, Form> = (_value, _scope, root) =>
   root.field1 > root.field2 ? { code: 'error', message: 'Invalid' } : null;
-const legacySchema = { field1: { value: model.$.field1, component: InputField, validators: [legacyRule] } };
+const legacySchema = { field1: { value: model.$.field1, component: Input, validators: [legacyRule] } };
 validateFormModel(model, legacySchema);
 
 // ✅ новое: cross-правило — обычная функция над снапшотом (model.get()), не читает scope/root
@@ -1677,11 +1714,13 @@ revalidateWhen([model.$.field2], () => void validateModel(model, schema));
 
 One form is one module folder. **Default layout — flat minimalist:** every concern is a single
 file at the module root, and the whole form (entry + all wizard steps inline) lives in one
-`index.tsx`. Filenames are flat with no prefix — **the dot-prefix (`form.` / `renderer.`) is
-carried only by `schema` and `behavior`**, the two concerns that have both a model-layer and a
-render-layer version (`form.schema.ts` / `form.behavior.ts` here; renderer slices add
-`renderer.schema.*` / `renderer.behavior.ts`). No `lib/` / `schema/` / `components/steps/`
-nesting until the form grows (see "Scaling up" below). Arrays are declared in `form.schema.ts`
+`index.tsx`. Naming rule: **`form.<role>` is a form artefact, the suffix names its role** —
+`form.schema.*` (layout), `form.behavior.ts` (model behavior), `form.render.ts` (render-layer
+behavior, renderer targets only), `form.validation.ts` (validation rules); every other file has
+no prefix. A wizard may instead keep each
+step's code in `steps/<slug>/` (same file names inside) with a `steps/index.ts` aggregator. The old
+`renderer.schema.*` / `renderer.behavior.ts` / `renderer.wizard.tsx` / `validation.ts` names still
+work with a warning. No `lib/` / `schema/` / `components/` nesting until the form grows (see "Scaling up" below). Arrays are declared in `form.schema.ts`
 and rendered with `FormArraySection` — no per-step component files.
 
 ```
@@ -1695,13 +1734,13 @@ src/
 │       ├── model.ts              # createModel + initial values + empty-array-element factories
 │       ├── form.schema.ts        # FormSchema: { value: model.$.x, component, componentProps }
 │       ├── form.behavior.ts      # defineFormBehavior: compute / enableWhen / hideWhen / copyFrom / onChange
-│       ├── validation.ts         # ALL validation → { validateStep, validateAll }
+│       ├── form.validation.ts    # ALL validation → { validateStep, validateAll }
 │       ├── data-sources.ts       # options + async loaders (dataSources)
 │       └── api.ts                # submit + prefill/load
 ```
 
 Rule of thumb: **one concern → one file at the module root; the whole component tree (all steps) →
-`index.tsx`; validation is a single `validation.ts`.** This is the working default for
+`index.tsx`; validation is a single `form.validation.ts`.** This is the working default for
 almost every form — reach for folders only when a file stops fitting on a screen.
 
 ### Key Files
@@ -1722,7 +1761,7 @@ export const createCreditApplicationModel = (): FormModel<CreditApplicationForm>
 // forms/credit-application/form.schema.ts
 import type { FormModel } from '@reformer/core';
 export const creditApplicationSchema = (model: FormModel<CreditApplicationForm>) => ({
-  loanType: { value: model.$.loanType, component: SelectField, componentProps: { /* ... */ } },
+  loanType: { value: model.$.loanType, component: SelectAsync, componentProps: { /* ... */ } },
   personalData: personalDataNodes(model.$.personalData),
   properties: { array: model.properties, item: propertyItem },
 });
@@ -1770,7 +1809,7 @@ forms/
     ├── schema/                   # The form definition
     │   ├── model.ts             # createModel factory + initial values + array-element factories
     │   ├── form.schema.ts       # schema builder (model) => tree ({ value: model.$.x, component })
-    │   ├── validation.ts        # defineValidationSchema + validateModel config ({ validateStep, validateAll })
+    │   ├── form.validation.ts   # defineValidationSchema + validateModel config ({ validateStep, validateAll })
     │   ├── form.behavior.ts     # defineFormBehavior(...)
     │   └── create-form.ts       # Assembly: createCoreForm({ model, schema, behavior, validation })
     │
@@ -1782,7 +1821,7 @@ forms/
 
 Rule of thumb for this layout: **domain raw material → `lib/`; anything describing the form →
 `schema/`; React layout → `components/`; root = entry + `index.ts`.** In very large forms you
-may co-locate each step's `form.schema.ts` / `validation.ts` / `form.behavior.ts` inside its
+may co-locate each step's `form.schema.ts` / `form.validation.ts` / `form.behavior.ts` inside its
 `steps/[Step]/` folder, keeping only the shared `model` and cross-step rules in `schema/` — see
 the guide below.
 
@@ -1798,9 +1837,9 @@ the guide below.
 > when registering the MCP server to choose which structure the generators lead with. Default
 > is `minimalist`.
 
-> Cross-target variants (renderer-react `renderer.schema.ts` + `renderer.behavior.ts` /
-> renderer-json `renderer.schema.ts` + `renderer.behavior.ts` + `registry.ts`, plus an optional
-> `renderer.wizard.tsx` shim), the `.tsx` / `.json` schema variants, the centralized-vs-co-located
+> Cross-target variants (renderer-react `form.schema.ts` + `form.render.ts` /
+> renderer-json `form.schema.ts` + `form.render.ts` + `registry.ts`, plus an optional
+> `wizard.tsx` shim), the `.tsx` / `.json` schema variants, the centralized-vs-co-located
 > choice, and the full reuse map live in the **form-directory-layout** guide (`@reformer/mcp`) —
 > `find_recipe directory-layout`.
 
@@ -1810,12 +1849,13 @@ the guide below.
 
 > **Default rule (read first)**: для UI используй `FormField` из
 > [`@reformer/ui-kit`](../../reformer-ui-kit/) — он покрывает 95% случаев одной
-> строкой `<FormField control={form.x} />`. Свои field-обёртки пиши ТОЛЬКО если
+> строкой `<FormField control={form.x} />`. Свои обёртки поля пиши ТОЛЬКО если
 > ui-kit не подходит (другая design system, особый low-level input).
 >
 > Канонический schema-driven подход:
 >
-> - **компонент** объявляется в схеме как `component: InputField` (или `Select`, `Checkbox`, etc.)
+> - **компонент** объявляется в схеме как `component: Input` (или `SelectAsync`, `CheckboxWithLabel`, …) —
+>   сам компонент кита, отдельных «field-версий» нет: связывает его с полем обёртка (`FormField`)
 > - **пропсы** компонента — в `componentProps: { label, placeholder, options, type, ... }`
 > - **JSX рендерит**: `<FormField control={form.x} />` БЕЗ дополнительных props
 >
@@ -1827,7 +1867,7 @@ the guide below.
 ```tsx
 import { useMemo } from 'react';
 import { createModel, createForm } from '@reformer/core';
-import { FormField, InputField, SelectField, CheckboxField, Button } from '@reformer/ui-kit';
+import { FormField, Input, SelectAsync, CheckboxWithLabel, Button } from '@reformer/ui-kit';
 
 type RegistrationForm = {
   email: string;
@@ -1841,12 +1881,12 @@ function RegistrationPage() {
     const schema = {
       email: {
         value: model.$.email,
-        component: InputField,
+        component: Input,
         componentProps: { label: 'Email', type: 'email', placeholder: 'you@example.com' },
       },
       country: {
         value: model.$.country,
-        component: SelectField,
+        component: SelectAsync,
         componentProps: {
           label: 'Country',
           options: [
@@ -1857,7 +1897,7 @@ function RegistrationPage() {
       },
       agree: {
         value: model.$.agree,
-        component: CheckboxField,
+        component: CheckboxWithLabel,
         componentProps: { label: 'I agree to terms' },
       },
     };
@@ -1900,7 +1940,7 @@ function RegistrationPage() {
 ✅ Всё это в схеме:
 
 ```ts
-{ email: { component: InputField, componentProps: { label: 'Email' } } }
+{ email: { component: Input, componentProps: { label: 'Email' } } }
 ```
 
 ```tsx
@@ -1921,7 +1961,8 @@ import { InputMask } from 'react-input-mask';
 ```
 
 `children` оборачивается в `CdkFormField.Control asChild` и получает все нужные
-props (`value`, `onChange`, `onBlur`, `aria-invalid`).
+props (`value`, `onChange`, `onBlur`, `aria-invalid`) — в диалекте ребёнка, если тот объявил
+статику `reformerAdapter` (`defineFieldControl` из `@reformer/ui-kit/fields`), иначе value-based.
 
 ### Advanced — write your own from scratch (rare)
 
@@ -1963,12 +2004,37 @@ function MyFormField<T>({ control }: MyFormFieldProps<T>) {
 <MyFormField control={form.email} /> // ← без label-prop
 ```
 
+### Связывание поля с контролом — `FieldAdapter` (`@reformer/core`)
+
+Контролы говорят на разных диалектах (`checked` + `onCheckedChange`, `onValueChange`, DOM-событие
+в `onChange`), форма — на value-based seam (`value` + `onChange(value)` + `onBlur`). Перевод
+описывает `FieldAdapter` (`valueProp`, `changeProp`, `fromEmit`, `toValue`, `bindBlur`, `strip`,
+`passControl` — все необязательны). Компонент объявляет его статикой `reformerAdapter`, а обёртка
+поля (`FormField.Control` из `@reformer/cdk`, рендерер `@reformer/renderer-react`) читает статику
+и связывает поле сама — отдельные «field-версии» компонентов не нужны.
+
+| Символ                        | Назначение                                                                  |
+| ----------------------------- | --------------------------------------------------------------------------- |
+| `FieldAdapter`                | Тип адаптера: диалект контрола                                              |
+| `getFieldAdapter(component)`  | Статика `component.reformerAdapter` либо `undefined`                        |
+| `bindFieldProps(adapter, seam, props)` | Props контрола под адаптер (без адаптера — seam как есть)          |
+| `FieldHandle`                 | Императивный handle поля: `focus` / `blur` / `scrollIntoView` / `getElement` |
+| `makeElementFieldHandle(ref)` | Базовый `FieldHandle` из DOM-узла                                           |
+| `useFieldHandleRef(outerRef)` | Ref для контрола + публикация handle потребителю (строит ОБЁРТКА поля)     |
+
+В приложении обычно достаточно `defineFieldControl(MyControl, { adapter })` из
+`@reformer/ui-kit/fields` (плюс готовые пресеты `checkedAdapter`, `valueChangeAdapter`, …); для
+компонентов чужой библиотеки без статики — `RendererSettings.resolveFieldAdapter`.
+
 ### Integration with UI libraries (shadcn etc.)
 
 > **Через рендерер — без обёртки.** Если ты рендеришь форму через `@reformer/renderer-react` /
 > `@reformer/renderer-json`, вместо ручной обёртки на каждый контрол можно зарегистрировать сырой
 > компонент и передать `settings.resolveFieldAdapter` — рендерер сам сведёт value-seam к диалекту
-> контрола. Ручная обёртка на `useFormControl` (ниже) нужна для прямого JSX без рендерера.
+> контрола. Свой компонент можно подготовить и один раз — статикой
+> `defineFieldControl(MyInput, { adapter })` из `@reformer/ui-kit/fields`: его поймут и рендерер,
+> и `FormField.Control` из `@reformer/cdk`. Ручная обёртка на `useFormControl` (ниже) нужна для
+> прямого JSX без `FormField` и рендерера.
 
 Если есть существующая design system — оборачивай её компоненты в один
 `MyFormField` (как выше) и используй один прop `control`. Не множь обёртки на
@@ -2026,6 +2092,20 @@ function ShadcnFormField({ control }: { control: FieldNode<string> }) {
 | `FormProvider`, `control` prop, `register()` | `<Component form={form} />`, `useFormControl(form.field)` | Форма передаётся через props |
 | `getFieldValue()`                | `model.field` / `useFormControlValue(form.field)`| Не существует                                   |
 
+### UI: удалённые field-версии компонентов (`@reformer/ui-kit`)
+
+Отдельных «field-версий» у компонентов кита больше нет: в `component` поля кладётся сам
+компонент, диалект он объявляет статикой `reformerAdapter`, связывает поле обёртка
+(`FormField.Control` / рендерер).
+
+| Wrong                                          | Correct                                                   |
+| ---------------------------------------------- | --------------------------------------------------------- |
+| `InputField`, `SelectField`, `CheckboxField`, … (любой `*Field`) | `Input`, `SelectAsync`, `CheckboxWithLabel`, … — таблица в ui-kit `01-overview.md` |
+| `InputField` + `type: 'number'`                | `InputNumber`                                             |
+| `InputField` + `suggestions`                   | `InputSuggest`                                            |
+| `FileUploadField` + `variant: 'dropzone' \| 'input'` | `FileUploadDropzone` / `FileUploadInput` (без `variant`) |
+| `withFormControl(MyControl, adapter)`          | `defineFieldControl(MyControl, { adapter })` из `@reformer/ui-kit/fields` |
+
 ### Common Import Errors
 
 ```typescript
@@ -2064,8 +2144,8 @@ const schema = {
 
 // CORRECT - layout только связывает поле с сигналом модели...
 const layout = {
-  name:  { value: model.$.name,  component: InputField, componentProps: { label: 'Name' } },
-  email: { value: model.$.email, component: InputField, componentProps: { label: 'Email' } },
+  name:  { value: model.$.name,  component: Input, componentProps: { label: 'Name' } },
+  email: { value: model.$.email, component: Input, componentProps: { label: 'Email' } },
 };
 
 // ...а правила — отдельная ambient-схема (прогоняется раннером validateModel):
@@ -3656,16 +3736,16 @@ Initial values задаются в `createModel(initial)`; `reset()` возвр
 
 ```typescript
 import { createModel, createForm } from '@reformer/core';
-import { InputField, SelectField } from '@reformer/ui-kit';
+import { Input, SelectAsync, CheckboxWithLabel } from '@reformer/ui-kit';
 
 type ProfileForm = { username: string; language: 'ru' | 'en'; marketing: boolean };
 
 const model = createModel<ProfileForm>({ username: '', language: 'ru', marketing: true });
 const schema = {
-  username: { value: model.$.username, component: InputField, componentProps: { label: 'Username' } },
+  username: { value: model.$.username, component: Input, componentProps: { label: 'Username' } },
   language: {
     value: model.$.language,
-    component: SelectField,
+    component: SelectAsync,
     componentProps: {
       label: 'Язык',
       options: [
@@ -3674,7 +3754,7 @@ const schema = {
       ],
     },
   },
-  marketing: { value: model.$.marketing, component: InputField, componentProps: { type: 'checkbox' } },
+  marketing: { value: model.$.marketing, component: CheckboxWithLabel, componentProps: { label: 'Рассылка' } },
 };
 const form = createForm({ model, schema });
 // model.get() === { username: '', language: 'ru', marketing: true }
@@ -3880,7 +3960,7 @@ Layout-схема БЕЗ валидаторов — правила живут в
 const model = createModel<CreditApplicationForm>(initial);
 
 const schema = {
-  loanAmount: { value: model.$.loanAmount, component: InputField },
+  loanAmount: { value: model.$.loanAmount, component: InputNumber },
   // вложенная группа — builder, принимающий ModelSignals<Sub>
   personalData: personalDataNodes(model.$.personalData),
   // массив — { array, item }
@@ -4422,7 +4502,280 @@ if (typeof window !== 'undefined') ctrl.start();
 - [31-async-validator-debounce.md](./31-async-validator-debounce.md) — async-правила и отмена устаревших прогонов
 - [13-multi-step.md](./13-multi-step.md) — per-step / полная валидация wizard (`validateStep` / `validateAll`)
 
-## 82. API Reference
+## 82. Purpose
+
+**i18n — локаль, загрузка словарей и провайдер**
+
+Подпуть `@reformer/core/i18n` — общий рантайм локализации для всех пакетов `@reformer/*`: объект
+локали, загрузка словарей, React-провайдер, перевод и форматирование. Язык задаётся провайдером,
+подгружается динамически и переключается на лету; узлы формы при этом не пересоздаются.
+
+Без провайдера всё работает на английском: у каждого пакета есть встроенная английская таблица.
+
+> Импорт всегда из `@reformer/core/i18n`. Из главной бочки `@reformer/core` этот модуль не
+> реэкспортируется: React-контекст локализации обязан существовать в одном экземпляре.
+
+## 83. Локаль — это данные
+
+```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` важнее),
+остальные поля заменяются.
+
+## 84. Формат сообщений — подмножество 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` языка локали.
+
+## 85. Загрузка локалей
+
+Откуда брать словарь, решает приложение: источник — функция `(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.*`) |
+
+## 86. Провайдер
+
+```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`.
+
+Вложенный провайдер заменяет локаль для своего поддерева целиком.
+
+## 87. Хуки
+
+```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')} />;
+}
+```
+
+## 88. Тексты ошибок валидации
+
+Правила из `@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` заменяет этот резолвер целиком:
+локаль для ошибок в его поддереве не участвует.
+
+## 89. Что показывается, когда ключа нет
+
+| Ключ                       | Нет в локали                                                    | Сообщение не разбирается                              |
+| -------------------------- | --------------------------------------------------------------- | ----------------------------------------------------- |
+| пакета (`useMessages`)     | встроенный английский пакета                                    | встроенный английский, `console.error` вне production |
+| приложения (`useI18n().t`) | `defaultMessage`, затем сам ключ; `console.warn` вне production | то же, `console.error`                                |
+
+Пропущенная подстановка выводится как `{name}`. Форма не падает ни в одном из случаев: неполный
+словарь, пришедший по сети, — законный сценарий.
+
+## 90. Проверка словаря в тестах
+
+```typescript
+import { validateLocale } from '@reformer/core/i18n';
+
+expect(validateLocale(ruJson, enJson)).toEqual([]);
+// находит: syntax (не разбирается), missing / extra (ключи), arguments (потерянная подстановка)
+```
+
+## 91. Описатели сообщений (низкий уровень)
+
+`msg(key, values?, defaultMessage?)` создаёт описатель сообщения, `defineMessages(appEn)` — `msg` с
+типизированными ключами, `resolveLocalized(value, i18n)` раскрывает описатели в объекте пропсов.
+
+> ⚠️ Рендереры и `FormField` описатели сами пока НЕ раскрывают. Не кладите `msg(...)` в
+> `componentProps` схемы: компонент получит объект вместо строки. До появления раскрытия в
+> рендерерах вызывайте `resolveLocalized` вручную или используйте `useI18n().t`.
+
+## 92. 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: {} });
+```
+
+## 93. See also
+
+- [28-submit-and-reset.md](./28-submit-and-reset.md) — жизненный цикл формы; смена языка его не затрагивает
+- [33-validation-strategy.md](./33-validation-strategy.md) — когда запускается валидация
+
+## 94. API Reference
 
 _Auto-generated from JSDoc on public exports._
 
@@ -4693,8 +5046,8 @@ export class ArrayNode<T extends object> extends FormNode<T[]> {
 
 ```typescript
 const array = new ArrayNode({
-  title: { value: '', component: InputField },
-  price: { value: 0, component: InputField },
+  title: { value: '', component: Input },
+  price: { value: 0, component: Input },
 });
 
 array.push({ title: 'Item 1', price: 100 });
@@ -4823,6 +5176,35 @@ export type BehaviorScope<T> = { model: FormModel<T>; form: FormProxy<T> };
 
 _Source: src/form/behaviors/types.ts_
 
+### bindFieldProps
+
+**Kind:** `function`
+
+Props контрола под адаптер: срезает служебные ключи обёртки и `strip` адаптера, кладёт значение
+в `valueProp` (через `toValue`), вешает `changeProp`, который прогоняет эмит контрола через
+`fromEmit` в value-based `onChange` поля, и пробрасывает blur (`bindBlur` либо `onBlur`).
+Без адаптера seam проходит как есть (`value` / `onChange` / `onBlur`).
+
+`componentProps` спредятся ПЕРВЫМИ — seam их перекрывает при совпадении ключей.
+
+**Signature:**
+```typescript
+export function bindFieldProps(
+  adapter: FieldAdapter | undefined,
+  seam: FieldSeam,
+  componentProps: Record<string, unknown> = {}
+): Record<string, unknown>
+```
+
+**Parameters:**
+- `adapter` — - Адаптер контрола или `undefined` (value-based контрол).
+- `seam` — - Значение поля и его колбэки.
+- `componentProps` — - Прочие props контрола.
+
+**Returns:** Плоский объект props для спреда в контрол.
+
+_Source: src/platforms/react/field-binding/field-adapter.ts_
+
 ### buildValidation
 
 **Kind:** `function`
@@ -4860,6 +5242,35 @@ await v!.validateAll();     // все шаги + extras
 
 _Source: src/form/validation/config.ts_
 
+### bundledLocaleSource
+
+**Kind:** `function`
+
+Источник встроенных локалей пакета: по чанку на язык. Язык ищется точно, затем по основной части
+кода (`ru-RU` → `ru`). Языка нет — источник отдаёт `null`: подписи пакета останутся английскими,
+пока приложение не даст их своим источником.
+
+**Signature:**
+```typescript
+export function bundledLocaleSource(
+  loaders: Readonly<Record<string, () => Promise<FormLocale>>>
+): LocaleSource
+```
+
+**Parameters:**
+- `loaders` — - Код языка → ленивый импорт его локали.
+
+**Examples:**
+
+```ts
+export const loadKitLocale = bundledLocaleSource({
+  en: () => import('./en').then((m) => m.en),
+  ru: () => import('./ru').then((m) => m.ru),
+});
+```
+
+_Source: src/i18n/loader.ts_
+
 ### ChangeContext
 
 **Kind:** `interface`
@@ -4977,6 +5388,19 @@ copyFrom(model.$.email, model.$.emailAdditional, { when: () => model.sameEmail }
 
 _Source: src/model/behaviors-value.ts_
 
+### CORE_LOCALES
+
+**Kind:** `const`
+
+Языки, которые ядро поставляет само.
+
+**Signature:**
+```typescript
+export const CORE_LOCALES: readonly string[]
+```
+
+_Source: src/locale/index.ts_
+
 ### CORE_RUNTIME_TOKEN
 
 **Kind:** `const`
@@ -5114,8 +5538,8 @@ const model = createModel<UserForm>({ email: '', password: '' });
 // Layout-схема НЕ несёт validators — только component/componentProps.
 const schema = {
 children: [
-{ value: model.$.email, component: InputField },
-{ value: model.$.password, component: InputField },
+{ value: model.$.email, component: Input },
+{ value: model.$.password, component: Input },
 ],
 };
 
@@ -5207,9 +5631,9 @@ const schema = {
 component: Section,
 children: [
 // Layout несёт только component/componentProps; правила — в отдельной ValidationSchema.
-{ value: model.$.email, component: InputField },
+{ value: model.$.email, component: Input },
 // вложенная группа: `model.$.profile.name` (≡ под-модель `model.profile.$.name` — тот же сигнал)
-{ value: model.$.profile.name, component: InputField },
+{ value: model.$.profile.name, component: Input },
 ],
 };
 
@@ -5287,6 +5711,122 @@ dispose();
 
 _Source: src/form/validation/strategy.ts_
 
+### createI18n
+
+**Kind:** `function`
+
+Ручка для локали. Для одного и того же объекта локали возвращается один и тот же объект —
+ручку можно держать в зависимостях хуков.
+
+**Signature:**
+```typescript
+export function createI18n(locale: FormLocale): I18nHandle
+```
+
+**Parameters:**
+- `locale` — - Локаль; см. {@link FormLocale}.
+
+**Examples:**
+
+```ts
+const i18n = createI18n({ code: 'ru', messages: { 'cart.items': '{count, plural, one{# товар} few{# товара} other{# товаров}}' } });
+i18n.t('cart.items', { count: 3 });  // '3 товара'
+i18n.fileSize(1536);                 // '1,5 КБ'
+```
+
+_Source: src/i18n/translator.ts_
+
+### createLocaleLoader
+
+**Kind:** `function`
+
+Собирает загрузчик из источников. Источники опрашиваются параллельно, а сливаются по порядку:
+поздний перекрывает ранний. Результат кэшируется по коду языка, идущий запрос не дублируется.
+Отказ любого источника — отказ загрузки; из кэша такой запрос удаляется, и следующая попытка
+пойдёт заново. Источник, которому можно промахнуться, приложение оборачивает само:
+`(code) => source(code).catch(() => null)`.
+
+Код языка у результата — всегда запрошенный: по нему работает `Intl`, и он не должен зависеть
+от того, что написано внутри файла.
+
+**Signature:**
+```typescript
+export function createLocaleLoader(sources: readonly LocaleSource[]): LocaleLoader
+```
+
+**Parameters:**
+- `sources` — - Источники в порядке возрастания приоритета.
+
+**Examples:**
+
+```ts
+import { createLocaleLoader, fetchMessages } from '@reformer/core/i18n';
+import { loadKitLocale } from '@reformer/ui-kit/locale';
+
+export const loadLocale = createLocaleLoader([
+  loadKitLocale,                                    // подписи кита — чанк нужного языка
+  fetchMessages((code) => `/locales/${code}.json`), // ключи приложения и правки — с сервера
+]);
+```
+
+_Source: src/i18n/loader.ts_
+
+### createLocaleStore
+
+**Kind:** `function`
+
+Создаёт хранилище. Загрузка при создании НЕ начинается: начальное состояние считается чисто —
+из кэша загрузчика, если локаль там уже есть, — а запрос уходит на первый {@link LocaleStore.setLang}.
+Это позволяет создавать хранилище прямо в рендере.
+
+**Signature:**
+```typescript
+export function createLocaleStore(
+  load: LocaleLoad,
+  lang: string,
+  options: LocaleStoreOptions = {}
+): LocaleStore
+```
+
+**Parameters:**
+- `load` — - Загрузчик локалей.
+- `lang` — - Начальный язык.
+- `options` — - См. {@link LocaleStoreOptions}.
+
+_Source: src/i18n/locale-store.ts_
+
+### createMessageFormatter
+
+**Kind:** `function`
+
+Форматтер одной локали с кэшем разбора: сообщение разбирается один раз, на первый вызов.
+Это внутренность `I18nService.t()` — сам `t()` добавляет сверху поиск ключа в словаре, маркер
+пропущенного ключа и откат на резервную локаль.
+
+**Signature:**
+```typescript
+export function createMessageFormatter(
+  locale: string,
+  options: MessageFormatOptions = {}
+): (source: string, values?: MessageValues) => string
+```
+
+**Parameters:**
+- `locale` — - Локаль форматтера.
+- `options` — - Настройки; см. {@link MessageFormatOptions}.
+
+**Returns:** Функция `(сообщение, значения) => строка`.
+
+**Examples:**
+
+```ts
+const format = createMessageFormatter('ru');
+format('{count, plural, one{# файл} few{# файла} many{# файлов} other{# файла}}', { count: 5 });
+// '5 файлов'
+```
+
+_Source: src/i18n/message-format.ts_
+
 ### createModel
 
 **Kind:** `function`
@@ -5341,6 +5881,20 @@ export function cross<TSnapshot>(
 
 _Source: src/form/validation/operators.ts_
 
+### DEFAULT_LOCALE
+
+**Kind:** `const`
+
+Локаль «провайдера нет»: английский, пустой словарь. Каждый пакет при промахе по словарю берёт
+свою встроенную английскую таблицу, поэтому пустой словарь означает «всё по-английски».
+
+**Signature:**
+```typescript
+export const DEFAULT_LOCALE: FormLocale
+```
+
+_Source: src/i18n/locale.ts_
+
 ### defer
 
 **Kind:** `function`
@@ -5377,6 +5931,37 @@ export const myBehavior = defineFormBehavior<MyForm>(({ model, form }) => {
 
 _Source: src/form/behaviors/context.ts_
 
+### defineMessages
+
+**Kind:** `function`
+
+`msg` с типизированными ключами: принимает английский словарь приложения, проверяет ключ при
+компиляции и подставляет английский текст как `defaultMessage` — без провайдера и при промахе
+по локали форма покажет его, а не ключ.
+
+**Signature:**
+```typescript
+export function defineMessages<D extends Messages>(
+  defaults: D
+): {
+  msg(key: keyof D & string, values?: Readonly<Record<string, unknown>>): MessageDescriptor;
+}
+```
+
+**Parameters:**
+- `defaults` — - Английский словарь приложения.
+
+**Examples:**
+
+```ts
+import appEn from './locales/en.json';
+
+export const { msg } = defineMessages(appEn);
+msg('profile.email.label'); // опечатка в ключе — ошибка компиляции
+```
+
+_Source: src/i18n/descriptor.ts_
+
 ### defineValidationSchema
 
 **Kind:** `function`
@@ -5435,7 +6020,8 @@ _Source: src/form/behaviors/node.ts_
 **Kind:** `function`
 
 Применить под-правила к КАЖДОМУ элементу текущего массива модели.
-`U extends object` — элементы должны быть под-моделями (объектами); для массива примитивов валидируйте лист напрямую.
+`U extends object` — элементы должны быть под-моделями (объектами); массив примитивов — одно
+значение поля, его проверяют целиком: `validate(model.$.<массив>, [...])`.
 
 **Signature:**
 ```typescript
@@ -5454,9 +6040,11 @@ _Source: src/form/validation/operators.ts_
 Обойти ВСЕ листовые сигналы модели (включая элементы массивов), вызвав `visit` на каждом.
 
 Внутри реактивного `effect` служит подпиской «любое поле изменилось»: `visit(sig => void sig.value)`
-подписывает на значения листьев, а обход массивов через `items.value` — на их состав. Так строятся
-триггеры `change`/`blur` стратегий валидации (см. `createFormValidation`), тем же паттерном, что
-`revalidateWhen`, но без ручного перечисления зависимостей.
+подписывает на значения листьев, а обход массивов через `items.value` — на их состав. Тот же
+паттерн, что `revalidateWhen`, но без ручного перечисления зависимостей.
+
+Сами массивы обход не посещает — только их элементы. Поле, привязанное к массиву целиком
+(мультивыбор), живёт на сигнале массива; чтобы увидеть и его, берите {@link eachValueSignal}.
 
 **Signature:**
 ```typescript
@@ -5468,18 +6056,40 @@ export function eachLeafSignal<T>(
 
 _Source: src/model/create-model.ts_
 
-### effect
+### eachValueSignal
 
 **Kind:** `function`
 
-Реактивный эффект (авто-dispose). Колбэк может вернуть собственный cleanup.
+Обойти ВСЕ ручки значений модели: листья (включая элементы массивов) И сами массивы.
+
+Отличие от {@link eachLeafSignal} — узлы-массивы: массив бывает одним значением поля
+(`{ value: model.$.tags, component }`), и нода такого поля привязана к сигналу массива, а не
+к сигналам элементов. Обходчику, которому нужна именно НОДА поля (стратегия `blur` подписывается
+на её `touched`), одних листьев мало — он не увидел бы мультивыбор. Так строятся триггеры
+`change`/`blur` стратегий валидации (см. `createFormValidation`).
 
 **Signature:**
 ```typescript
-export function effect(fn: () => void | (() => void)): void
+export function eachValueSignal<T>(
+  model: FormModel<T>,
+  visit: (signal: PathAwareSignal<unknown>) => void
+): void
 ```
 
-_Source: src/form/behaviors/context.ts_
+_Source: src/model/create-model.ts_
+
+### effect
+
+**Kind:** `function`
+
+Реактивный эффект (авто-dispose). Колбэк может вернуть собственный cleanup.
+
+**Signature:**
+```typescript
+export function effect(fn: () => void | (() => void)): void
+```
+
+_Source: src/form/behaviors/context.ts_
 
 ### email
 
@@ -5641,6 +6251,136 @@ exclusiveFlag(model.$.contacts, (row) => row.$.primary);
 
 _Source: src/form/behaviors/collections.ts_
 
+### extendLocale
+
+**Kind:** `function`
+
+Новая локаль на основе существующей: словари сливаются (ключи из `patch` важнее), остальные
+поля заменяются. Исходный объект не меняется.
+
+**Signature:**
+```typescript
+export function extendLocale(base: FormLocale, patch: Partial<FormLocale>): FormLocale
+```
+
+**Parameters:**
+- `base` — - Локаль-основа, например поставляемая китом.
+- `patch` — - Свои ключи, переопределения китовых подписей и поля локали.
+
+**Examples:**
+
+```ts
+import { ru } from '@reformer/ui-kit/locale/ru';
+
+const appRu = extendLocale(ru, {
+  messages: { 'profile.title': 'Профиль', 'kit.formWizard.submit': 'Отправить' },
+});
+```
+
+_Source: src/i18n/locale.ts_
+
+### fetchMessages
+
+**Kind:** `function`
+
+Источник локали по сети: забирает JSON по адресу, построенному из кода языка. Файл может быть
+словарём (`{ "profile.title": "Профиль" }`) или локалью целиком (`{ "code": "ru", "messages": … }`).
+Ответ не `2xx` — ошибка загрузки.
+
+**Signature:**
+```typescript
+export function fetchMessages(url: (code: string) => string, init?: RequestInit): LocaleSource
+```
+
+**Parameters:**
+- `url` — - Адрес файла для языка.
+- `init` — - Параметры запроса, передаются в `fetch` как есть.
+
+**Examples:**
+
+```ts
+fetchMessages((code) => `/locales/${code}.json`);
+```
+
+_Source: src/i18n/loader.ts_
+
+### FIELD_WRAPPER_ONLY_PROPS
+
+**Kind:** `const`
+
+Props, которые адресованы обёртке поля, а не контролу: `labelTooltip` рисует `FormField` у
+подписи. Они приходят в общем мешке `componentProps`, и без среза утекли бы в DOM контрола.
+
+**Signature:**
+```typescript
+export const FIELD_WRAPPER_ONLY_PROPS: readonly string[]
+```
+
+_Source: src/platforms/react/field-binding/field-adapter.ts_
+
+### FieldAdapter
+
+**Kind:** `interface`
+
+Адаптер поля: описывает диалект контрола (`checked`/`onCheckedChange`, `value`/`onValueChange`,
+DOM-событие в `onChange`, …). Все ключи необязательны — по умолчанию seam проходит как есть.
+
+**Signature:**
+```typescript
+export interface FieldAdapter {
+  /** Проп, из которого контрол читает значение (по умолчанию `'value'`). */
+  valueProp?: string;
+  /** Колбэк, через который контрол эмитит изменение (по умолчанию `'onChange'`). */
+  changeProp?: string;
+  /**
+   * Эмит контрола → значение поля (по умолчанию — как есть). `rest` — прочие props контрола
+   * (например, чтобы достать `options` при резолве значения).
+   */
+  fromEmit?: (arg: unknown, rest: Record<string, unknown>) => unknown;
+  /** Значение поля → `valueProp` контрола (коэрсия `null`/`undefined`; по умолчанию — как есть). */
+  toValue?: (value: unknown) => unknown;
+  /** Проброс blur нестандартным каналом (по умолчанию — `onBlur`). */
+  bindBlur?: (onBlur: () => void) => Record<string, unknown>;
+  /** Ключи, которые убрать из `componentProps` перед спредом в контрол. */
+  strip?: string[];
+  /**
+   * Передавать ли контролу ноду формы пропом `control` (только рендерер). По умолчанию `false`:
+   * errors/touched обслуживает обёртка поля. Ставь `true`, если контрол сам вызывает
+   * `useFormControl(control)`.
+   */
+  passControl?: boolean;
+}
+```
+
+**Examples:**
+
+Radix Checkbox
+```ts
+const checkedAdapter: FieldAdapter = {
+valueProp: 'checked',
+changeProp: 'onCheckedChange',
+fromEmit: (c) => c === true,
+toValue: (v) => v ?? false,
+};
+```
+
+_Source: src/platforms/react/field-binding/field-adapter.ts_
+
+### FieldAdapterCarrier
+
+**Kind:** `interface`
+
+Компонент, объявивший свой диалект статикой.
+
+**Signature:**
+```typescript
+export interface FieldAdapterCarrier {
+  reformerAdapter?: FieldAdapter;
+}
+```
+
+_Source: src/platforms/react/field-binding/field-adapter.ts_
+
 ### FieldConfig
 
 **Kind:** `interface`
@@ -5746,11 +6486,12 @@ export interface FieldControlState<T> {
    * @example
    * ```tsx
    * const { errors } = useFormControl(field);
+   * const message = useValidationMessage(); // из '@reformer/core/i18n'
    *
    * return (
    *   <ul className="error-list">
    *     {errors.map((error, i) => (
-   *       <li key={i}>{error.message}</li>
+   *       <li key={i}>{message(error)}</li>
    *     ))}
    *   </ul>
    * );
@@ -5813,12 +6554,13 @@ export interface FieldControlState<T> {
    * @example
    * ```tsx
    * const { shouldShowError, errors } = useFormControl(field);
+   * const message = useValidationMessage(); // из '@reformer/core/i18n'
    *
    * return (
    *   <div>
    *     <input {...props} />
    *     {shouldShowError && (
-   *       <span className="error">{errors[0]?.message}</span>
+   *       <span className="error">{message(errors[0])}</span>
    *     )}
    *   </div>
    * );
@@ -5881,6 +6623,7 @@ control: FieldNode<string>;
 
 function TextField({ control }: Props) {
 const state = useFormControl(control);
+const message = useValidationMessage(); // из '@reformer/core/i18n'
 
 return (
 <div>
@@ -5890,7 +6633,7 @@ disabled={state.disabled}
 onChange={e => control.setValue(e.target.value)}
 />
 {state.shouldShowError && state.errors[0] && (
-<span className="error">{state.errors[0].message}</span>
+<span className="error">{message(state.errors[0])}</span>
 )}
 </div>
 );
@@ -5903,6 +6646,38 @@ onChange={e => control.setValue(e.target.value)}
 
 _Source: src/platforms/react/hooks/types.ts_
 
+### FieldHandle
+
+**Kind:** `interface`
+
+Базовый императивный контракт поля формы.
+
+Обёртка поля (`FormField.Control` из `@reformer/cdk`, рендерер `@reformer/renderer-react`)
+строит его из DOM-узла контрола. Композиты со своим handle (`open`/`close`/`reload`/…) отдают
+его как есть — он расширяет этот контракт.
+
+Достаётся из render-схемы по селектору:
+`schema.node(sel).getRef<FieldHandle>().current?.focus()`.
+
+Покрывает ТОЛЬКО императивные действия. Реактивное состояние (value / disabled / options /
+validation) живёт в behaviors и через handle не дублируется.
+
+**Signature:**
+```typescript
+export interface FieldHandle {
+  /** Сфокусировать поле (делегирует на DOM-элемент контрола). */
+  focus(): void;
+  /** Снять фокус. */
+  blur(): void;
+  /** Проскроллить поле в область видимости. */
+  scrollIntoView(opts?: ScrollIntoViewOptions): void;
+  /** Живой DOM-элемент поля (или `null` до монтирования / для размонтированной ноды). */
+  getElement(): HTMLElement | null;
+}
+```
+
+_Source: src/platforms/react/field-binding/field-handle.ts_
+
 ### FieldNode
 
 **Kind:** `class`
@@ -5923,7 +6698,7 @@ export class FieldNode<T> extends FormNode<T> {
 ```typescript
 const field = new FieldNode({
   value: '',
-  component: InputField,
+  component: Input,
   validators: [required, email],
 });
 
@@ -5934,6 +6709,23 @@ console.log(field.valid.value); // true
 
 _Source: src/form/nodes/field-node.ts_
 
+### FieldSeam
+
+**Kind:** `interface`
+
+Seam поля: текущее значение и value-based колбэки.
+
+**Signature:**
+```typescript
+export interface FieldSeam {
+  value: unknown;
+  onChange: (value: unknown) => void;
+  onBlur: () => void;
+}
+```
+
+_Source: src/platforms/react/field-binding/field-adapter.ts_
+
 ### FieldStatus
 
 **Kind:** `type`
@@ -6064,6 +6856,33 @@ todos.forEach((item, i) => {
 
 _Source: src/form/types/form-proxy.ts_
 
+### formatPattern
+
+**Kind:** `function`
+
+Собирает строку из разобранного сообщения. Значения подставляются как текст и повторно
+не разбираются.
+
+**Signature:**
+```typescript
+export function formatPattern(
+  pattern: MessagePattern,
+  values: MessageValues,
+  locale: string,
+  options: MessageFormatOptions = {}
+): string
+```
+
+**Parameters:**
+- `pattern` — - Результат {@link parseMessage}.
+- `values` — - Значения аргументов.
+- `locale` — - Локаль для {@link Intl.PluralRules} и {@link Intl.NumberFormat} (`ru`, `en`, …).
+- `options` — - Настройки; см. {@link MessageFormatOptions}.
+
+**Returns:** Готовая строка интерфейса.
+
+_Source: src/i18n/message-format.ts_
+
 ### FormBehavior
 
 **Kind:** `interface`
@@ -6209,6 +7028,43 @@ try {
 
 _Source: src/form/validation/error-handler.ts_
 
+### FormLocale
+
+**Kind:** `interface`
+
+Локаль формы.
+
+**Signature:**
+```typescript
+export interface FormLocale {
+  /** Код языка BCP 47 (`en`, `ru`, `pt-BR`): по нему работают `Intl` и множественные формы. */
+  readonly code: string;
+  /** Словарь сообщений. Ключа нет — пакет подставит встроенный английский. */
+  readonly messages: Messages;
+  /** Первый день недели календаря. По умолчанию — воскресенье. */
+  readonly weekStartsOn?: WeekStart;
+  /**
+   * Необязательное переопределение: объект локали `react-day-picker` / `date-fns`. Для ядра
+   * непрозрачен. Без него даты форматируются через `Intl` по {@link FormLocale.code}.
+   */
+  readonly dateLocale?: unknown;
+  /** Необязательное переопределение: формат даты в токенах `date-fns` для DatePicker. */
+  readonly dateFormat?: string;
+}
+```
+
+**Examples:**
+
+```ts
+const ru: FormLocale = {
+  code: 'ru',
+  weekStartsOn: 1,
+  messages: { 'kit.select.selected': 'Выбрано: {count}' },
+};
+```
+
+_Source: src/i18n/locale.ts_
+
 ### FormModel
 
 **Kind:** `type`
@@ -6374,14 +7230,14 @@ interface Form {
 }
 
 const schema: FormSchema<Form> = {
-  name: { value: '', component: InputField },
+  name: { value: '', component: Input },
   address: {
-    city: { value: '', component: InputField },
-    street: { value: '', component: InputField },
+    city: { value: '', component: Input },
+    street: { value: '', component: Input },
   },
   items: [{
-    title: { value: '', component: InputField },
-    price: { value: 0, component: InputField },
+    title: { value: '', component: Input },
+    price: { value: 0, component: Input },
   }],
 };
 ```
@@ -6642,6 +7498,26 @@ validate(model.$.appointmentDate, [required(), futureDate({ message: 'Дата
 
 _Source: src/form/validators/future-date.ts_
 
+### getFieldAdapter
+
+**Kind:** `function`
+
+Адаптер, объявленный компонентом статикой `reformerAdapter`, либо `undefined`.
+
+**Signature:**
+```typescript
+export function getFieldAdapter(component: unknown): FieldAdapter | undefined
+```
+
+**Examples:**
+
+```ts
+Checkbox.reformerAdapter = checkedAdapter;
+getFieldAdapter(Checkbox); // → checkedAdapter
+```
+
+_Source: src/platforms/react/field-binding/field-adapter.ts_
+
 ### getNodeForSignal
 
 **Kind:** `function`
@@ -6738,8 +7614,8 @@ export class GroupNode<T> extends FormNode<T> {
 
 ```typescript
 const form = new GroupNode({
-  email: { valueSignal: model.$.email, component: InputField },
-  password: { valueSignal: model.$.password, component: InputField },
+  email: { valueSignal: model.$.email, component: Input },
+  password: { valueSignal: model.$.password, component: Input },
 });
 
 // Прямой доступ к полям через Proxy
@@ -6770,6 +7646,163 @@ export interface GroupNodeConfig<T> {
 
 _Source: src/form/types/index.ts_
 
+### I18N_CONTEXT_MARKER
+
+**Kind:** `const`
+
+Имя контекста и одновременно маркер, по которому страж ищет его копии в сборках.
+
+**Signature:**
+```typescript
+export const I18N_CONTEXT_MARKER
+```
+
+_Source: src/platforms/react/i18n/context.ts_
+
+### I18nContextValue
+
+**Kind:** `interface`
+
+Что видит компонент: ручка активной локали и состояние её загрузки.
+
+**Signature:**
+```typescript
+export interface I18nContextValue extends I18nHandle {
+  /** Идёт загрузка другого языка; на экране пока прежний. Без загрузчика всегда `false`. */
+  readonly pending: boolean;
+  /** Ошибка последней загрузки языка. */
+  readonly error: unknown;
+}
+```
+
+_Source: src/platforms/react/i18n/context.ts_
+
+### I18nHandle
+
+**Kind:** `interface`
+
+Ручка локали: перевод и форматирование по одному языку.
+
+**Signature:**
+```typescript
+export interface I18nHandle {
+  /** Локаль, по которой работает ручка. */
+  readonly locale: FormLocale;
+  /** Код языка — то же, что `locale.code`. */
+  readonly code: string;
+  /** Есть ли ключ в словаре локали (встроенные английские таблицы не учитываются). */
+  has(key: string): boolean;
+  /**
+   * Перевод ключа приложения: словарь локали → `defaultMessage` → встроенная таблица ядра → ключ.
+   *
+   * @param key - Ключ сообщения.
+   * @param values - Значения подстановок.
+   * @param defaultMessage - Английский текст на случай, если ключа в локали нет.
+   */
+  t(key: string, values?: MessageValues, defaultMessage?: string): string;
+  /** Число по правилам языка. */
+  number(value: number, options?: Intl.NumberFormatOptions): string;
+  /** Дата по правилам языка. */
+  date(value: Date | number, options?: Intl.DateTimeFormatOptions): string;
+  /** Размер файла: `1536` → `1.5 KB` (`1,5 КБ` в русской локали). База — 1024. */
+  fileSize(bytes: number): string;
+}
+```
+
+_Source: src/i18n/translator.ts_
+
+### I18nLoadingProviderProps
+
+**Kind:** `interface`
+
+Режим «провайдер грузит сам».
+
+**Signature:**
+```typescript
+export interface I18nLoadingProviderProps {
+  /** Код языка. Смена кода запускает загрузку; до её конца на экране прежний язык. */
+  lang: string;
+  /** Загрузчик локалей — обычно результат `createLocaleLoader`. */
+  load: LocaleLoad;
+  /**
+   * Что показать, пока не загружена самая первая локаль. По умолчанию — ничего: иначе на кадр
+   * мелькнул бы встроенный английский. Если локаль уже в кэше загрузчика (`load.preload(lang)`
+   * до монтирования), первый рендер синхронный и `fallback` не показывается.
+   */
+  fallback?: ReactNode;
+  /** Отказ загрузки. Язык на экране при этом не меняется. */
+  onError?: (error: unknown, lang: string) => void;
+  children?: ReactNode;
+}
+```
+
+_Source: src/platforms/react/i18n/provider.ts_
+
+### I18nProvider
+
+**Kind:** `function`
+
+Провайдер локализации для подписей компонентов, ошибок валидации и авторских подписей формы.
+Без провайдера компоненты говорят встроенным английским.
+
+При смене `lang` на экране остаётся прежний язык, пока новый не загрузится (`useI18n().pending`
+— для индикатора). При быстром переключении применяется только последний запрос. Вложенный
+провайдер заменяет локаль для своего поддерева целиком.
+
+**Signature:**
+```typescript
+export function I18nProvider(props: I18nProviderProps): ReactElement | null
+```
+
+**Examples:**
+
+Провайдер грузит локаль сам
+```tsx
+const [lang, setLang] = useState('ru');
+
+<I18nProvider lang={lang} load={loadLocale}>
+<LangSwitch value={lang} onChange={setLang} />
+<CreditForm />
+</I18nProvider>
+```
+
+Готовая локаль — SSR и тесты
+```tsx
+import { ru } from '@reformer/ui-kit/locale/ru';
+
+<I18nProvider locale={ru}><CreditForm /></I18nProvider>
+```
+
+_Source: src/platforms/react/i18n/provider.ts_
+
+### I18nProviderProps
+
+**Kind:** `type`
+
+**Signature:**
+```typescript
+export type I18nProviderProps = I18nStaticProviderProps | I18nLoadingProviderProps;
+```
+
+_Source: src/platforms/react/i18n/provider.ts_
+
+### I18nStaticProviderProps
+
+**Kind:** `interface`
+
+Режим «готовая локаль».
+
+**Signature:**
+```typescript
+export interface I18nStaticProviderProps {
+  /** Локаль. Смена объекта переключает язык сразу. */
+  locale: FormLocale;
+  children?: ReactNode;
+}
+```
+
+_Source: src/platforms/react/i18n/provider.ts_
+
 ### integer
 
 **Kind:** `function`
@@ -7015,6 +8048,19 @@ if (isGroupNode(node)) {
 
 _Source: src/form/type-guards.ts_
 
+### isMessageDescriptor
+
+**Kind:** `function`
+
+Является ли значение описателем сообщения.
+
+**Signature:**
+```typescript
+export function isMessageDescriptor(value: unknown): value is MessageDescriptor
+```
+
+_Source: src/i18n/descriptor.ts_
+
 ### isModelContainerSignal
 
 **Kind:** `function`
@@ -7075,25 +8121,240 @@ validate(model.$.amount, [required(), isNumber({ message: 'Введите чис
 
 _Source: src/form/validators/is-number.ts_
 
-### markDerived
+### isValueSignal
 
 **Kind:** `function`
 
-Пометить сигнал производным (вычисляемым).
-
-Вызывается операторами {@link computeFrom}/`compute` для их сигнала-цели. После этого
-bulk-сеттеры (`model.set`/`model.patch`, `patchValue`/`setValue`) пропускают это поле, чтобы
-значение из payload не затирало вычисляемое. Прикладной код напрямую обычно не вызывает.
+«Ручка значения», к которой можно привязать поле: лист (`instanceof Signal`) либо узел-массив
+дерева `model.$` (значение — массив целиком, `.value` читается и пишется).
 
-Идемпотентна на уровне флага: повторные вызовы наращивают счётчик ссылок, чтобы каждый оператор,
-пишущий в этот сигнал, был сбалансирован своим {@link unmarkDerived} при dispose.
+Группа сюда не входит: она читается целиком, но не пишется и полем не бывает. Этой проверкой
+`createForm` и рендереры отличают узел-поле схемы (`{ value, component }`) от контейнера —
+вместо голого `value instanceof Signal`, который узел-массив не проходит.
 
 **Signature:**
 ```typescript
-export function markDerived(signal: Signal<any>): void
+export function isValueSignal(value: unknown): value is Signal<unknown>
 ```
 
-**Parameters:**
+**Examples:**
+
+```typescript
+const model = createModel({ name: '', tags: [] as string[], address: { city: '' } });
+isValueSignal(model.$.name);    // true — лист
+isValueSignal(model.$.tags);    // true — массив как значение
+isValueSignal(model.$.address); // false — группа
+```
+
+_Source: src/model/model-signals-proxy.ts_
+
+### loadCoreLocale
+
+**Kind:** `const`
+
+Источник локалей ядра для `createLocaleLoader`: чанк нужного языка по запросу.
+
+**Signature:**
+```typescript
+export const loadCoreLocale
+```
+
+**Examples:**
+
+```ts
+const loadLocale = createLocaleLoader([loadCoreLocale, fetchMessages((code) => `/locales/${code}.json`)]);
+```
+
+_Source: src/locale/index.ts_
+
+### LocaleIssue
+
+**Kind:** `interface`
+
+Что не так со словарём.
+
+**Signature:**
+```typescript
+export interface LocaleIssue {
+  readonly key: string;
+  /**
+   * - `syntax` — сообщение не разбирается;
+   * - `missing` — ключ есть в образце, но его нет в словаре;
+   * - `extra` — ключа нет в образце;
+   * - `arguments` — набор подстановок не совпадает с образцом.
+   */
+  readonly kind: 'syntax' | 'missing' | 'extra' | 'arguments';
+  readonly message: string;
+}
+```
+
+_Source: src/i18n/locale.ts_
+
+### LocaleLoad
+
+**Kind:** `interface`
+
+Функция загрузки локали. `peek` — необязательный синхронный кэш (есть у `createLocaleLoader`).
+
+**Signature:**
+```typescript
+export interface LocaleLoad {
+  (code: string): Promise<FormLocale>;
+  peek?(code: string): FormLocale | undefined;
+}
+```
+
+_Source: src/i18n/locale-store.ts_
+
+### LocaleLoader
+
+**Kind:** `interface`
+
+Загрузчик локалей с кэшем.
+
+**Signature:**
+```typescript
+export interface LocaleLoader {
+  /** Загрузить локаль языка. Повторный вызов возвращает тот же промис и ту же локаль. */
+  (code: string): Promise<FormLocale>;
+  /** Уже загруженная локаль или `undefined`. Позволяет провайдеру отрисоваться синхронно. */
+  peek(code: string): FormLocale | undefined;
+  /** То же, что вызов загрузчика; имя для чтения в коде старта приложения. */
+  preload(code: string): Promise<FormLocale>;
+}
+```
+
+_Source: src/i18n/loader.ts_
+
+### LocaleSource
+
+**Kind:** `type`
+
+Источник локали. Получает код языка, отдаёт локаль или словарь — сразу или промисом.
+`null`/`undefined` означает «для этого языка у меня ничего нет» и ошибкой не считается.
+
+**Signature:**
+```typescript
+export type LocaleSource = (code: string) => LocaleSourceResult | Promise<LocaleSourceResult>;
+```
+
+_Source: src/i18n/loader.ts_
+
+### LocaleSourceResult
+
+**Kind:** `type`
+
+Что может вернуть источник: локаль целиком, её часть, голый словарь или ничего.
+
+**Signature:**
+```typescript
+export type LocaleSourceResult = Partial<FormLocale> | Messages | null | undefined;
+```
+
+_Source: src/i18n/loader.ts_
+
+### LocaleStore
+
+**Kind:** `interface`
+
+Хранилище активной локали.
+
+**Signature:**
+```typescript
+export interface LocaleStore {
+  getState(): LocaleStoreState;
+  subscribe(listener: () => void): () => void;
+  /** Запросить язык. Повторный запрос того же языка, пока он грузится или уже показан, — no-op. */
+  setLang(lang: string): void;
+}
+```
+
+_Source: src/i18n/locale-store.ts_
+
+### LocaleStoreOptions
+
+**Kind:** `interface`
+
+Настройки хранилища.
+
+**Signature:**
+```typescript
+export interface LocaleStoreOptions {
+  /** Вызывается при отказе загрузки языка, который всё ещё запрошен. */
+  readonly onError?: (error: unknown, lang: string) => void;
+}
+```
+
+_Source: src/i18n/locale-store.ts_
+
+### LocaleStoreState
+
+**Kind:** `interface`
+
+Состояние хранилища. Объект неизменяемый: новая ссылка — новое состояние.
+
+**Signature:**
+```typescript
+export interface LocaleStoreState {
+  /** Запрошенный язык. Пока `pending`, может отличаться от языка `locale`. */
+  readonly lang: string;
+  /** Локаль, которая сейчас на экране; `null` — ни одна ещё не загружена. */
+  readonly locale: FormLocale | null;
+  /** Идёт загрузка запрошенного языка. */
+  readonly pending: boolean;
+  /** Ошибка последней загрузки; сбрасывается следующей удачной. */
+  readonly error: unknown;
+}
+```
+
+_Source: src/i18n/locale-store.ts_
+
+### LocalizableText
+
+**Kind:** `type`
+
+Текст, который можно задать строкой или описателем.
+
+**Signature:**
+```typescript
+export type LocalizableText = string | MessageDescriptor;
+```
+
+_Source: src/i18n/descriptor.ts_
+
+### makeElementFieldHandle
+
+**Kind:** `function`
+
+Собирает базовый {@link FieldHandle}, делегирующий на DOM-элемент по ссылке `el`.
+Все вызовы null-safe: до монтирования (`el.current === null`) — no-op, без исключений.
+
+**Signature:**
+```typescript
+export function makeElementFieldHandle(el: RefObject<HTMLElement | null>): FieldHandle
+```
+
+_Source: src/platforms/react/field-binding/field-handle.ts_
+
+### markDerived
+
+**Kind:** `function`
+
+Пометить сигнал производным (вычисляемым).
+
+Вызывается операторами {@link computeFrom}/`compute` для их сигнала-цели. После этого
+bulk-сеттеры (`model.set`/`model.patch`, `patchValue`/`setValue`) пропускают это поле, чтобы
+значение из payload не затирало вычисляемое. Прикладной код напрямую обычно не вызывает.
+
+Идемпотентна на уровне флага: повторные вызовы наращивают счётчик ссылок, чтобы каждый оператор,
+пишущий в этот сигнал, был сбалансирован своим {@link unmarkDerived} при dispose.
+
+**Signature:**
+```typescript
+export function markDerived(signal: Signal<any>): void
+```
+
+**Parameters:**
 - `signal` — - Сигнал значения из {@link FormModel}, которым владеет compute
 
 **Examples:**
@@ -7317,103 +8578,261 @@ export function maxFileSize<TForm = unknown, TField = unknown>(
 - `options` — - Опции валидатора ({@link ValidateOptions}). В `params` ошибки автоматически
 попадают `maxFileSize`, `fileName` и `actualSize`.
 
-**Returns:** Чистый валидатор {@link Validator} для файла или массива файлов
+**Returns:** Чистый валидатор {@link Validator} для файла или массива файлов
+
+**Examples:**
+
+Ограничение размера вложений
+```typescript
+import { defineValidationSchema, validate } from '@reformer/core/validation';
+import { maxFileSize } from '@reformer/core/validators';
+
+// Правила живут в отдельной схеме над МОДЕЛЬЮ — layout-схема валидаторов не несёт.
+const validation = defineValidationSchema<MyForm>(({ model }) => {
+validate(model.$.documents, [maxFileSize(5 * 1024 * 1024, { message: 'Файл больше 5 МБ' })]);
+});
+```
+
+_Source: src/form/validators/max-file-size.ts_
+
+### maxLength
+
+**Kind:** `function`
+
+Фабрика валидатора максимальной длины строки или массива.
+
+Работает со строкой или массивом (проверяется `value.length`). Пустые значения
+(`null`/`undefined`/`''`) и значения без числового `length` пропускаются
+(используйте {@link required} для обязательности).
+
+**Signature:**
+```typescript
+export function maxLength<TForm = unknown, TField = unknown>(
+  maxLen: number,
+  options?: ValidateOptions
+): Validator<TForm, TField>
+```
+
+**Parameters:**
+- `maxLen` — - Максимально допустимая длина (включительно)
+- `options` — - Опции валидатора ({@link ValidateOptions}). В `params` ошибки автоматически
+попадают `maxLength` и `actualLength`.
+
+**Returns:** Чистый валидатор {@link Validator} для строки или массива
+
+**Examples:**
+
+Максимальная длина строки
+```typescript
+import { defineValidationSchema, validate } from '@reformer/core/validation';
+import { maxLength } from '@reformer/core/validators';
+
+// Правила живут в отдельной схеме над МОДЕЛЬЮ — layout-схема валидаторов не несёт.
+const validation = defineValidationSchema<MyForm>(({ model }) => {
+validate(model.$.name, [maxLength(50)]);
+validate(model.$.bio, [maxLength(500, { message: 'Максимум 500 символов' })]);
+});
+```
+
+_Source: src/form/validators/max-length.ts_
+
+### maxTotalFileSize
+
+**Kind:** `function`
+
+Фабрика валидатора суммарного размера всех файлов.
+
+Складывает `size` всех файлов значения (элементы без числового `size` в сумму
+не входят). Пустые значения (`null`/`undefined`/`''`/`[]`) пропускаются
+(используйте {@link required} для обязательности).
+
+**Signature:**
+```typescript
+export function maxTotalFileSize<TForm = unknown, TField = unknown>(
+  maxTotal: number,
+  options?: ValidateOptions
+): Validator<TForm, TField>
+```
+
+**Parameters:**
+- `maxTotal` — - Максимально допустимый суммарный размер в байтах (включительно)
+- `options` — - Опции валидатора ({@link ValidateOptions}). В `params` ошибки автоматически
+попадают `maxTotalFileSize` и `actualTotal`.
+
+**Returns:** Чистый валидатор {@link Validator} для файла или массива файлов
+
+**Examples:**
+
+Суммарно не более 20 МБ
+```typescript
+import { defineValidationSchema, validate } from '@reformer/core/validation';
+import { maxTotalFileSize } from '@reformer/core/validators';
+
+// Правила живут в отдельной схеме над МОДЕЛЬЮ — layout-схема валидаторов не несёт.
+const validation = defineValidationSchema<MyForm>(({ model }) => {
+validate(model.$.documents, [maxTotalFileSize(20 * 1024 * 1024, { message: 'Суммарно не более 20 МБ' })]);
+});
+```
+
+_Source: src/form/validators/max-total-file-size.ts_
+
+### MESSAGE_DESCRIPTOR
+
+**Kind:** `const`
+
+Бренд описателя. `Symbol.for` — чтобы описатель узнавался и через границу двух копий модуля
+(разные чанки, разные версии пакета на странице).
+
+**Signature:**
+```typescript
+export const MESSAGE_DESCRIPTOR: unique symbol
+```
+
+_Source: src/i18n/descriptor.ts_
+
+### messageArguments
+
+**Kind:** `function`
+
+Имена аргументов сообщения, включая те, что встречаются только внутри веток `plural`/`select`.
+
+**Signature:**
+```typescript
+export function messageArguments(
+  pattern: MessagePattern,
+  out: Set<string> = new Set()
+): Set<string>
+```
+
+**Parameters:**
+- `pattern` — - Результат `parseMessage`.
+
+_Source: src/i18n/locale.ts_
+
+### MessageBranches
+
+**Kind:** `type`
+
+Ветки `plural`/`select`: категория CLDR (`one`, `few`, …), точное совпадение (`=0`) или значение `select`.
+
+**Signature:**
+```typescript
+export type MessageBranches = ReadonlyMap<string, MessagePattern>;
+```
+
+_Source: src/i18n/message-format.ts_
+
+### MessageDescriptor
+
+**Kind:** `interface`
+
+Описатель сообщения. Намеренно без ключей `value`, `array`, `item`, `component`: обход схемы в
+`createForm` узнаёт по ним узел, а описатель узлом не является.
+
+**Signature:**
+```typescript
+export interface MessageDescriptor {
+  readonly [MESSAGE_DESCRIPTOR]: true;
+  /** Ключ сообщения в словаре приложения. */
+  readonly key: string;
+  /** Значения подстановок. */
+  readonly values?: Readonly<Record<string, unknown>>;
+  /** Английский текст на случай, если ключа в локали нет. */
+  readonly defaultMessage?: string;
+}
+```
+
+_Source: src/i18n/descriptor.ts_
+
+### MessageFormatOptions
+
+**Kind:** `interface`
+
+Настройки форматирования.
+
+**Signature:**
+```typescript
+export interface MessageFormatOptions {
+  /**
+   * Что подставить вместо аргумента, которого нет в значениях (или чьё значение не число там, где
+   * ожидалось число). По умолчанию — заметный маркер `⟦name⟧`, тот же приём, что и для пропущенного
+   * ключа: пропуск должен попадаться разработчику, а не пользователю.
+   */
+  readonly onMissingArgument?: (name: string) => string;
+}
+```
+
+_Source: src/i18n/message-format.ts_
+
+### MessageNode
+
+**Kind:** `type`
 
-**Examples:**
+Узел разобранного сообщения.
 
-Ограничение размера вложений
+**Signature:**
 ```typescript
-import { defineValidationSchema, validate } from '@reformer/core/validation';
-import { maxFileSize } from '@reformer/core/validators';
-
-// Правила живут в отдельной схеме над МОДЕЛЬЮ — layout-схема валидаторов не несёт.
-const validation = defineValidationSchema<MyForm>(({ model }) => {
-validate(model.$.documents, [maxFileSize(5 * 1024 * 1024, { message: 'Файл больше 5 МБ' })]);
-});
+export type MessageNode =
+  | { readonly kind: 'text'; readonly value: string }
+  | { readonly kind: 'arg'; readonly name: string }
+  | { readonly kind: 'number'; readonly name: string }
+  | { readonly kind: 'plural'; readonly name: string; readonly branches: MessageBranches }
+  | { readonly kind: 'select'; readonly name: string; readonly branches: MessageBranches };
 ```
 
-_Source: src/form/validators/max-file-size.ts_
-
-### maxLength
+_Source: src/i18n/message-format.ts_
 
-**Kind:** `function`
+### MessagePattern
 
-Фабрика валидатора максимальной длины строки или массива.
+**Kind:** `type`
 
-Работает со строкой или массивом (проверяется `value.length`). Пустые значения
-(`null`/`undefined`/`''`) и значения без числового `length` пропускаются
-(используйте {@link required} для обязательности).
+Разобранное сообщение — плоская последовательность узлов.
 
 **Signature:**
 ```typescript
-export function maxLength<TForm = unknown, TField = unknown>(
-  maxLen: number,
-  options?: ValidateOptions
-): Validator<TForm, TField>
+export type MessagePattern = readonly MessageNode[];
 ```
 
-**Parameters:**
-- `maxLen` — - Максимально допустимая длина (включительно)
-- `options` — - Опции валидатора ({@link ValidateOptions}). В `params` ошибки автоматически
-попадают `maxLength` и `actualLength`.
+_Source: src/i18n/message-format.ts_
 
-**Returns:** Чистый валидатор {@link Validator} для строки или массива
+### Messages
 
-**Examples:**
+**Kind:** `type`
 
-Максимальная длина строки
-```typescript
-import { defineValidationSchema, validate } from '@reformer/core/validation';
-import { maxLength } from '@reformer/core/validators';
+Плоский словарь: ключ → сообщение в формате ICU (см. `message-format.ts`).
 
-// Правила живут в отдельной схеме над МОДЕЛЬЮ — layout-схема валидаторов не несёт.
-const validation = defineValidationSchema<MyForm>(({ model }) => {
-validate(model.$.name, [maxLength(50)]);
-validate(model.$.bio, [maxLength(500, { message: 'Максимум 500 символов' })]);
-});
+**Signature:**
+```typescript
+export type Messages = Readonly<Record<string, string>>;
 ```
 
-_Source: src/form/validators/max-length.ts_
-
-### maxTotalFileSize
+_Source: src/i18n/locale.ts_
 
-**Kind:** `function`
+### MessageSyntaxError
 
-Фабрика валидатора суммарного размера всех файлов.
+**Kind:** `class`
 
-Складывает `size` всех файлов значения (элементы без числового `size` в сумму
-не входят). Пустые значения (`null`/`undefined`/`''`/`[]`) пропускаются
-(используйте {@link required} для обязательности).
+Отказ разбора сообщения: синтаксис или отсутствие обязательной ветки `other`.
 
 **Signature:**
 ```typescript
-export function maxTotalFileSize<TForm = unknown, TField = unknown>(
-  maxTotal: number,
-  options?: ValidateOptions
-): Validator<TForm, TField>
+export class MessageSyntaxError extends Error { /* … */ }
 ```
 
-**Parameters:**
-- `maxTotal` — - Максимально допустимый суммарный размер в байтах (включительно)
-- `options` — - Опции валидатора ({@link ValidateOptions}). В `params` ошибки автоматически
-попадают `maxTotalFileSize` и `actualTotal`.
+_Source: src/i18n/message-format.ts_
 
-**Returns:** Чистый валидатор {@link Validator} для файла или массива файлов
+### MessageValues
 
-**Examples:**
+**Kind:** `type`
 
-Суммарно не более 20 МБ
-```typescript
-import { defineValidationSchema, validate } from '@reformer/core/validation';
-import { maxTotalFileSize } from '@reformer/core/validators';
+Значения аргументов сообщения.
 
-// Правила живут в отдельной схеме над МОДЕЛЬЮ — layout-схема валидаторов не несёт.
-const validation = defineValidationSchema<MyForm>(({ model }) => {
-validate(model.$.documents, [maxTotalFileSize(20 * 1024 * 1024, { message: 'Суммарно не более 20 МБ' })]);
-});
+**Signature:**
+```typescript
+export type MessageValues = Readonly<Record<string, unknown>>;
 ```
 
-_Source: src/form/validators/max-total-file-size.ts_
+_Source: src/i18n/message-format.ts_
 
 ### min
 
@@ -7691,7 +9110,10 @@ export interface ModelApi<T> {
   reset(): void;
   /** Зафиксировать текущие значения как новый initial-снимок («точка отсчёта»). */
   captureInitial(): void;
-  /** Резолв строкового пути в сигнал (для error-routing/мостов). */
+  /**
+   * Резолв строкового пути в сигнал (для error-routing/мостов): лист либо массив целиком
+   * (ручка значения массива — см. {@link ModelArraySignals}). Для пути группы — `undefined`.
+   */
   signalAt(path: string): PathAwareSignal<unknown> | undefined;
 }
 ```
@@ -7796,8 +9218,8 @@ export class ModelArrayNode<T extends object> extends FormNode<T[]> { /* … */
 const model = createModel<{ rows: { name: string; qty: number }[] }>({ rows: [] });
 
 const rowItem = (item: FormModel<{ name: string; qty: number }>) => ({
-name: { value: item.$.name, component: InputField },
-qty: { value: item.$.qty, component: InputField },
+name: { value: item.$.name, component: Input },
+qty: { value: item.$.qty, component: Input },
 });
 
 const form = createForm({
@@ -7820,12 +9242,23 @@ _Source: src/form/nodes/model-array-node.ts_
 **Kind:** `type`
 
 Узел-массив дерева `model.$`: индексируемый доступ к под-сигналам элементов, реактивная `length`
-и {@link ReadonlySignal} значения массива целиком (реагирует и на правку элемента, и на изменение
-состава — push/removeAt/move).
+и сигнал значения массива целиком (реагирует и на правку элемента, и на изменение состава —
+push/removeAt/move).
+
+В отличие от группы, узел ЗАПИСЫВАЕМ: `model.$.tags.value = ['a']` заменяет массив целиком. Это
+делает его {@link PathAwareSignal} — к нему привязывают поле (`{ value: model.$.tags, component }`),
+правило (`validate(model.$.tags, …)`) и поведение, как к листу. Так массив служит ОДНИМ значением
+поля: мультивыбор, теги, список файлов.
+
+`V` — объявленный тип поля, включая `null`/`undefined`: поле `string[] | null` с начальным `null`
+в рантайме — лист с тем же `.value`/`peek`/`subscribe`, поэтому общая часть честна для обоих
+случаев. `length` и индексы есть только у настоящего узла-массива (начальное значение — массив).
 
 **Signature:**
 ```typescript
-export type ModelArraySignals<U, V> = ContainerSignal<V, 'length'> & {
+export type ModelArraySignals<U, V> = Signal<V> & {
+  /** Путь массива в модели (dot-нотация). */
+  readonly __path: string;
   readonly length: number;
   readonly [index: number]: ModelSignalNode<U>;
 };
@@ -7908,6 +9341,34 @@ export type ModelValue<V> =
 
 _Source: src/model/types.ts_
 
+### msg
+
+**Kind:** `function`
+
+Создаёт описатель сообщения.
+
+**Signature:**
+```typescript
+export function msg(
+  key: string,
+  values?: Readonly<Record<string, unknown>>,
+  defaultMessage?: string
+): MessageDescriptor
+```
+
+**Parameters:**
+- `key` — - Ключ в словаре приложения.
+- `values` — - Значения подстановок.
+- `defaultMessage` — - Английский текст на случай, если ключа в локали нет.
+
+**Examples:**
+
+```ts
+{ value: model.$.email, component: Input, componentProps: { label: msg('profile.email.label') } }
+```
+
+_Source: src/i18n/descriptor.ts_
+
 ### multipleOf
 
 **Kind:** `function`
@@ -7980,25 +9441,25 @@ export class NodeFactory {
    * // FieldNode
    * const field = factory.createNode({
    *   value: 'test@mail.com',
-   *   component: InputField,
+   *   component: Input,
    *   validators: [required, email]
    * });
    *
    * // GroupNode
    * const group = factory.createNode({
-   *   email: { value: '', component: InputField },
-   *   password: { value: '', component: InputField }
+   *   email: { value: '', component: Input },
+   *   password: { value: '', component: Input }
    * });
    *
    * // ArrayNode (объект)
    * const array = factory.createNode({
-   *   schema: { title: { value: '', component: InputField } },
+   *   schema: { title: { value: '', component: Input } },
    *   initialItems: [{ title: 'Item 1' }]
    * });
    *
    * // ArrayNode (массив) - новый формат
    * const array2 = factory.createNode([
-   *   { title: { value: '', component: InputField } }, // schema
+   *   { title: { value: '', component: Input } }, // schema
    *   { title: 'Item 1' }, // initial item 1
    *   { title: 'Item 2' }  // initial item 2
    * ]);
@@ -8012,7 +9473,7 @@ export class NodeFactory {
 import { NodeFactory } from '@reformer/core';
 
 const factory = new NodeFactory();
-const node = factory.createNode({ value: '', component: InputField }); // → FieldNode<string>
+const node = factory.createNode({ value: '', component: Input }); // → FieldNode<string>
 ```
 
 _Source: src/form/factories/node-factory.ts_
@@ -8124,6 +9585,31 @@ export function onDispose(cleanup: BehaviorCleanup): void
 
 _Source: src/form/behaviors/context.ts_
 
+### parseMessage
+
+**Kind:** `function`
+
+Разбирает сообщение в дерево. Бросает {@link MessageSyntaxError} на ошибке синтаксиса и на
+`plural`/`select` без ветки `other`.
+
+**Signature:**
+```typescript
+export function parseMessage(source: string): MessagePattern
+```
+
+**Parameters:**
+- `source` — - Текст сообщения из словаря.
+
+**Returns:** Разобранное сообщение для {@link formatPattern}.
+
+**Examples:**
+
+```ts
+parseMessage('{count, plural, one{# файл} few{# файла} many{# файлов} other{# файла}}');
+```
+
+_Source: src/i18n/message-format.ts_
+
 ### pastDate
 
 **Kind:** `function`
@@ -8388,6 +9874,60 @@ resetWhen(model.$.cardNumber, () => model.paymentType !== 'card', { resetValue:
 
 _Source: src/model/behaviors-value.ts_
 
+### resolveLocalized
+
+**Kind:** `function`
+
+Заменяет описатели сообщений на строки по активной локали. Обходит массивы и простые
+объекты-литералы — подписи опций, заголовки шагов; сигналы, React-элементы, функции и
+экземпляры классов (узлы формы) возвращает как есть. Поддерево без описателей сохраняет ссылку:
+если раскрывать было нечего, возвращается тот же объект.
+
+**Signature:**
+```typescript
+export function resolveLocalized<T>(value: T, i18n: I18nHandle): T
+```
+
+**Parameters:**
+- `value` — - Пропсы, массив или одиночное значение.
+- `i18n` — - Ручка активной локали (`createI18n` / `useI18n`).
+
+**Examples:**
+
+```ts
+resolveLocalized({ label: msg('profile.email.label'), options: [{ value: 'a', label: msg('opt.a') }] }, i18n);
+// { label: 'Почта', options: [{ value: 'a', label: 'Вариант А' }] }
+```
+
+_Source: src/i18n/resolve-localized.ts_
+
+### resolveValidationError
+
+**Kind:** `function`
+
+Отображаемый текст ошибки валидации. Порядок источников — в шапке модуля.
+
+**Signature:**
+```typescript
+export function resolveValidationError(error: ValidationError, i18n: I18nHandle): string
+```
+
+**Parameters:**
+- `error` — - Ошибка от правила: `code`, `message`, `messageKey`, `params`.
+- `i18n` — - Ручка активной локали (`createI18n` / `useI18n`).
+
+**Examples:**
+
+```ts
+resolveValidationError({ code: 'minLength', message: '', params: { minLength: 8 } }, i18n);
+// 'Enter at least 8 characters' · в русской локали — 'Не меньше 8 символов'
+
+resolveValidationError({ code: 'required', message: 'Укажите телефон' }, i18n);
+// 'Укажите телефон' — явное сообщение автора важнее словаря
+```
+
+_Source: src/i18n/validation-message.ts_
+
 ### revalidateWhen
 
 **Kind:** `function`
@@ -8752,6 +10292,32 @@ transformValue(model.$.promoCode, (v) => (v ?? '').toUpperCase());
 
 _Source: src/model/behaviors-value.ts_
 
+### translateBuiltin
+
+**Kind:** `function`
+
+Перевод ключа пакета: словарь локали, затем встроенная английская таблица пакета, затем сам
+ключ. Английская таблица форматируется по английским правилам — её множественные формы и
+группировка чисел не зависят от активного языка.
+
+**Signature:**
+```typescript
+export function translateBuiltin(
+  locale: FormLocale,
+  builtin: Messages,
+  key: string,
+  values?: MessageValues
+): string
+```
+
+**Parameters:**
+- `locale` — - Активная локаль.
+- `builtin` — - Встроенная английская таблица пакета-владельца ключа.
+- `key` — - Ключ сообщения.
+- `values` — - Значения подстановок.
+
+_Source: src/i18n/translator.ts_
+
 ### UnknownRecord
 
 **Kind:** `type`
@@ -8901,6 +10467,33 @@ function ArrayRenderer({ arrayNode }) {
 
 _Source: src/platforms/react/hooks/useArrayLength.ts_
 
+### useFieldHandleRef
+
+**Kind:** `function`
+
+Ref для контрола поля + императивный handle для потребителя.
+
+Возвращённый ref вешается на контрол. На `outerRef` публикуется:
+- handle самого контрола, если тот его реализует (`useImperativeHandle` композита);
+- иначе — базовый {@link FieldHandle}, построенный из DOM-узла контрола.
+
+Хук вызывается безусловно; вешать ref на контрол стоит только при заданном `outerRef` —
+так function-компонент без ref-поддержки не получает лишний ref.
+
+**Signature:**
+```typescript
+export function useFieldHandleRef<H = FieldHandle>(
+  outerRef: Ref<H> | undefined
+): RefObject<unknown>
+```
+
+**Parameters:**
+- `outerRef` — - ref потребителя (из `forwardRef` или `schema.node(sel).getRef()`).
+
+**Returns:** ref, который нужно передать контролу.
+
+_Source: src/platforms/react/field-binding/field-handle.ts_
+
 ### useFormBundle
 
 **Kind:** `function`
@@ -8968,6 +10561,7 @@ export function useFormControl(
 Текстовое поле с валидацией
 ```tsx
 import { useFormControl } from '@reformer/core';
+import { useValidationMessage } from '@reformer/core/i18n';
 import type { FieldNode } from '@reformer/core';
 
 interface TextFieldProps {
@@ -8983,6 +10577,8 @@ shouldShowError,
 errors,
 pending
 } = useFormControl(control);
+// Текст ошибки даёт резолвер: у правил без своего сообщения `message` пуст.
+const message = useValidationMessage();
 
 return (
 <div className="field">
@@ -9002,7 +10598,7 @@ return (
 
 {shouldShowError && errors[0] && (
 <span className="error" role="alert">
- {errors[0].message}
+ {message(errors[0])}
 </span>
 )}
 </div>
@@ -9050,6 +10646,7 @@ control: FieldNode<string>;
 
 function Select({ control }: SelectProps) {
 const { value, disabled, componentProps, shouldShowError, errors } = useFormControl(control);
+const message = useValidationMessage(); // из '@reformer/core/i18n'
 const options = componentProps.options as Array<{ value: string; label: string }>;
 
 return (
@@ -9067,7 +10664,7 @@ onBlur={() => control.markAsTouched()}
  </option>
 ))}
 </select>
-{shouldShowError && <span className="error">{errors[0]?.message}</span>}
+{shouldShowError && <span className="error">{message(errors[0])}</span>}
 </div>
 );
 }
@@ -9305,6 +10902,7 @@ dangerouslySetInnerHTML={{ __html: html }}
 // Основной редактор использует useFormControl для полного состояния
 function MarkdownEditor({ control }: MarkdownEditorProps) {
 const { value, shouldShowError, errors } = useFormControl(control);
+const message = useValidationMessage(); // из '@reformer/core/i18n'
 
 return (
 <div className="editor-container">
@@ -9312,7 +10910,7 @@ return (
 value={value}
 onChange={e => control.setValue(e.target.value)}
 />
-{shouldShowError && <span className="error">{errors[0]?.message}</span>}
+{shouldShowError && <span className="error">{message(errors[0])}</span>}
 
 {/* Preview обновляется только при изменении value *}
 <MarkdownPreview control={control} />
@@ -9416,12 +11014,104 @@ export interface UseFormValidationResult {
 
 _Source: src/platforms/react/hooks/use-form-validation.ts_
 
+### useI18n
+
+**Kind:** `function`
+
+Активная локаль: перевод ключей приложения, форматирование чисел, дат и размеров, состояние
+загрузки языка. Без провайдера — английский с пустым словарём.
+
+**Signature:**
+```typescript
+export function useI18n(): I18nContextValue
+```
+
+**Examples:**
+
+```tsx
+function LangBadge() {
+  const { code, pending, t } = useI18n();
+  return <span aria-busy={pending}>{t('app.language')}: {code}</span>;
+}
+```
+
+_Source: src/platforms/react/i18n/hooks.ts_
+
+### useMessages
+
+**Kind:** `function`
+
+Переводчик пакета: ищет ключ в локали провайдера, а при промахе берёт встроенную английскую
+таблицу этого пакета. Так пакет говорит по-английски без провайдера и не зависит от того, знает
+ли локаль его ключи. Тип ключа выводится из таблицы — опечатка в ключе не скомпилируется.
+
+`defaults` должен быть стабильной ссылкой (импорт JSON-модуля), иначе переводчик будет
+пересоздаваться на каждый рендер.
+
+**Signature:**
+```typescript
+export function useMessages<D extends Messages>(
+  defaults: D
+): (key: keyof D & string, values?: MessageValues) => string
+```
+
+**Parameters:**
+- `defaults` — - Встроенная английская таблица пакета.
+
+**Returns:** Функция `(ключ, значения?) => строка`; её идентичность меняется вместе с локалью.
+
+**Examples:**
+
+```tsx
+import en from './locale/en.json';
+
+const useKitMessages = () => useMessages(en);
+
+function ClearButton() {
+  const t = useKitMessages();
+  return <button aria-label={t('kit.select.clear')} />;
+}
+```
+
+_Source: src/platforms/react/i18n/hooks.ts_
+
+### useValidationMessage
+
+**Kind:** `function`
+
+Резолвер текста ошибки валидации по активной локали: `messageKey` автора → явное `message` →
+словарь локали по коду → встроенный английский → код. Идентичность функции меняется вместе с
+локалью, поэтому показанные ошибки переводятся при смене языка без повторной валидации.
+
+`FormField` из `@reformer/cdk` использует его сам; вызывайте напрямую, если рисуете ошибки
+своим компонентом.
+
+**Signature:**
+```typescript
+export function useValidationMessage(): (error: ValidationError) => string
+```
+
+**Examples:**
+
+```tsx
+function FieldErrors({ control }: { control: FieldNode<string> }) {
+  const message = useValidationMessage();
+  const { errors } = useFormControl(control);
+  return <>{errors.map((error) => <span key={error.code}>{message(error)}</span>)}</>;
+}
+```
+
+_Source: src/platforms/react/i18n/hooks.ts_
+
 ### validate
 
 **Kind:** `function`
 
 Синхронные правила поля.
 
+Поле — лист либо массив целиком: `model.$.<массив>` — такая же ручка значения, и правило
+получает массив (мультивыбор, теги, список файлов).
+
 **Signature:**
 ```typescript
 export function validate<TField>(sig: PathAwareSignal<TField>, rules: Rule<TField>[]): void
@@ -9431,6 +11121,7 @@ export function validate<TField>(sig: PathAwareSignal<TField>, rules: Rule<TFiel
 
 ```ts
 validate(model.$.loanAmount, [required({ message: 'Сумма' }), min(50000)]);
+validate(model.$.tags, [required(), maxLength(3)]); // tags: string[] — массив как значение
 ```
 
 _Source: src/form/validation/operators.ts_
@@ -9461,6 +11152,34 @@ validateAsync(model.$.username, [async (v, { signal }) => {
 
 _Source: src/form/validation/operators.ts_
 
+### validateLocale
+
+**Kind:** `function`
+
+Проверяет словарь: каждое сообщение разбирается, а при заданном образце — набор ключей и имена
+подстановок совпадают с ним. Нужна там, где компилятор не поможет: словарь пришёл по сети или
+написан вне репозитория. В рантайме вызывать не обязательно — битое или пропущенное сообщение
+и так откатится на встроенный английский; проверка нужна тестам и CI.
+
+**Signature:**
+```typescript
+export function validateLocale(messages: Messages, reference?: Messages): LocaleIssue[]
+```
+
+**Parameters:**
+- `messages` — - Проверяемый словарь.
+- `reference` — - Образец, обычно английский словарь того же пакета.
+
+**Returns:** Список расхождений; пустой — словарь в порядке.
+
+**Examples:**
+
+```ts
+expect(validateLocale(ruJson, enJson)).toEqual([]);
+```
+
+_Source: src/i18n/locale.ts_
+
 ### validateModel
 
 **Kind:** `function`
@@ -9517,8 +11236,20 @@ _Source: src/form/validation/run.ts_
 ```typescript
 export interface ValidateOptions {
   /** Готовое сообщение об ошибке. Если не задано, валидаторы кладут `''`, и отображаемый текст
-   * резолвится из `code` (см. резолвер сообщений в `@reformer/cdk`). */
+   * берётся из словаря локали по `code` (`validation.<code>`; см. `resolveValidationError` в
+   * `@reformer/core/i18n`). Явное сообщение важнее словаря, но не переключается вместе с языком —
+   * для локализуемого текста используйте {@link ValidateOptions.messageKey}. */
   message?: string;
+  /**
+   * Ключ сообщения в словаре приложения — локализуемый текст автора правила. Если ключ есть в
+   * активной локали, он важнее и `message`, и текста по `code`; если нет — в ход идёт `message`.
+   *
+   * @example
+   * ```ts
+   * required({ messageKey: 'profile.name.required', message: 'Name is required' });
+   * ```
+   */
+  messageKey?: string;
   /** Параметры ошибки (подстановка в шаблон сообщения / i18n). */
   params?: Record<string, FormValue>;
 }
@@ -9550,7 +11281,13 @@ _Source: src/form/validation/operators.ts_
 ```typescript
 export interface ValidationError {
   code: string;
+  /**
+   * Готовый текст ошибки. Пустая строка — «автор правила текста не задавал»: отображаемую строку
+   * тогда даёт резолвер по `code` (словарь локали `validation.<code>`).
+   */
   message: string;
+  /** Ключ сообщения в словаре приложения; при наличии в активной локали важнее `message`. */
+  messageKey?: string;
   params?: Record<string, FormValue>;
   /** Severity level: 'error' (default) blocks submission, 'warning' shows message but allows submission */
   severity?: 'error' | 'warning';
@@ -9670,3 +11407,16 @@ watchField(model.$.country, async (country) => {
 ```
 
 _Source: src/model/behaviors-value.ts_
+
+### WeekStart
+
+**Kind:** `type`
+
+День недели, с которого начинается календарь: `0` — воскресенье, `1` — понедельник.
+
+**Signature:**
+```typescript
+export type WeekStart = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+```
+
+_Source: src/i18n/locale.ts_