ADR-0002: Catalog-first i18n contract

Статус: accepted
Дата: 2026-07-16

Context

Digitable-продукты работают как web, embedded, desktop и store builds. Без общего контракта агенты добавляют locale через локальные условные ветки, переключают меню отдельно от контента и по-разному трактуют fallback, accessibility и platform language codes.

Decision

Все пользовательские продукты используют catalog-first i18n architecture:

один locale lifecycle и normalization adapter;
стабильные semantic message IDs;
typed или schema-validated catalog parity;
отдельные contracts для UI и длинного content при общих locale rules;
Intl или ICU-compatible formatting;
локализованные accessibility surfaces;
обязательные runtime, responsive и platform mapping checks.

Supported locales, source/fallback, translation approval и content scope остаются решениями project-specific SDD.

Consequences

Положительные:

AI-агенты и команды добавляют языки одинаковым способом;
смешение языков и пропущенные ключи обнаруживаются до release;
embedded, desktop и storefront adapters используют одно состояние locale;
редакторский статус generated content становится наблюдаемым.

Trade-offs:

каждый новый locale требует полного catalog/content gate;
migration от inline copy может занимать отдельную итерацию;
platform language codes требуют явных adapters.

Verification

playbook содержит owning contract и SDD checklist;
template SDD запрашивает localization contract;
template agent bootstrap направляет к общему документу;
make check и production site build проходят.