Вывод типов и валидация

ts-intl задействует систему типов TypeScript для проверки несуществующих ключей, отсутствующих параметров и несоответствий структуры многоязычных словарей.

Проверка ключей и автодополнение

При использовании пространств имён или путей через точку IDE поддерживает автодополнение ключей и проверку типов:

const tCommon = getTranslations("ru-RU", "common");
tCommon("title"); // Автодополнение: "title" | "greeting" | "items"

// @ts-expect-error
tCommon("title_misspelled");

Глобальный вызов через путь с точкой (dot-path):

const tRoot = getTranslations("ru-RU");
tRoot("common.title"); // Автодополнение: "common.title" | "common.greeting" | ...

Ограничения параметров

Если шаблон содержит плейсхолдеры, передача соответствующего объекта с параметрами обязательна. Если в шаблоне нет плейсхолдеров, передача лишних аргументов запрещена:

const t = getTranslations("ru-RU", "common");

// Без плейсхолдеров: передача параметров запрещена
t("title");

// С плейсхолдером: передача параметров обязательна
t("greeting", { name: "Алиса" });

// @ts-expect-error Отсутствует обязательный параметр { name: string }
t("greeting");

Явные аннотации типов параметров

В словарях TypeScript скалярные типы параметров можно указывать явно с помощью синтаксиса {name:type}. В настоящее время поддерживаются string, number и Date:

export default {
  status:
    "Пользователь {name: string} вошёл в систему в {timestamp: Date}. Всего: {total: number}",
} as const;

TypeScript проверяет типы параметров, переданных вызывающей стороной:

const t = getTranslations("ru-RU");

t("status", {
  name: "Алиса",
  timestamp: new Date(),
  total: 42,
});

// @ts-expect-error Тип 'string' не может быть назначен типу 'number'
t("status", { name: "Алиса", timestamp: new Date(), total: "42" });

Соответствие структуры многоязычных словарей (Schema Alignment)

Словарь языка, указанного в defaultLanguage, принимается за эталонную структуру. Все остальные языки, настроенные в messages, должны строго ей соответствовать:

• Если в других языках отсутствуют ключи, ошибка типа возникает прямо в конфигурации инициализации.
• Если в других языках присутствуют лишние ключи, которых нет в эталонном языке, возникает ошибка типа.
• Имена переменных в плейсхолдерах должны совпадать во всех языках (например, если в английском используется {count}, то в русском также должно быть {count}).

const ruRU = {
  welcome: "Добро пожаловать, {user: string}!",
} as const;

const enUS = {
  // @ts-expect-error Отсутствует ключ 'welcome'
  farewell: "Goodbye",
} as const;

createI18n({
  defaultLanguage: "ru-RU",
  messages: { "ru-RU": ruRU, "en-US": enUS },
});

Валидация словарей во время выполнения (Runtime)

В среде разработки (не в production-режиме) функция createI18n выполняет валидацию словарей на этапе инициализации:

• Проверяет, не содержат ли ключи словаря случайно точки . (точка является зарезервированным символом иерархии пространств имён).
• Отправляет диагностические предупреждения через onError при обнаружении структурных расхождений.

Эта валидация автоматически отключается в production-сборках, не создавая никаких дополнительных накладных расходов во время выполнения.