Одна из главных проблем i18n в приложениях заключается в том, что о ней вспоминают в последнюю очередь.

Обычно мы разрабатываем продукт, проверяем соответствие рынку (Product-Market Fit) и только спустя месяцы или годы решаем: «Пора выходить на глобальный уровень».

Сложность в том, что решения для i18n носят структурный характер и сильно влияют на работу команды. Куда эффективнее закладывать это в техническое задание с первого дня.

Как же с этим справиться? Заморозить разработку на неделю и рефакторить каждый компонент?

В последнее время я вижу много решений, основанных на compiler-driven подходе. Обещание заманчивое: добавьте пару строк кода, и приложение «само» станет мультиязычным.

Однако есть существенные недостатки.

Всем привет!

Долго я возился с маркдауном в своих проектах и, честно говоря, знатно подгорел. Первая проблема — это вечный выбор библиотеки.

С одной стороны, есть «конструкторы» типа unified, remark и rehype. Штуки мощные, но настраивать весь этот AST-конвейер и систему плагинов — это какой-то оверхед и лишняя сложность, имхо.

С другой стороны, есть @next/mdx, который вроде и ок, но слишком завязан на страницах и вообще не умеет работать на клиенте.

Раньше я обычно выбирал что-то вроде markdown-to-jsx или react-markdown.

DX у них приятнее, работают и на клиенте, и на сервере, весят мало.

Но вот беда: они «из коробки» не переваривают HTML или MDX, и ты снова вязнешь в настройке плагинов. А если добавить туда i18n (типа i18next или next-intl), начинается настоящий ад. Куча if/else в коде, чтобы отрендерить нужный язык, и бандл раздувается до небес. Плюс вечные косяки с front-matter. Ну и до недавнего времени всё это было только для React.

В общем, решил я написать свое решение для intlayer. Чтобы просто работало.

> К слову, за основу я взял форк markdown-to-jsx v7.7.14 (от quantizor), который базируется на simple-markdown v0.2.2 (от Khan Academy).

Когда пилил этот парсер, ставил перед собой такие цели:

- Максимально легкий вес

- Кросс-фреймворковость (React, Vue, Svelte, Angular, Solid, Preact)

- Простая настройка: никаких бесконечных цепочек плагинов

- Поддержка SSR и клиентского рендеринга

- Настройка на уровне провайдера: можно легко прокинуть свои компоненты из дизайн-системы

- Компонентный подход: полный контроль над рендерингом каждой части приложения

Подход по компонентам — не новое понятие. Например, в экосистеме Vue vue-i18n поддерживает [i18n SFC (Single File Component)](https://vue-i18n.intlify.dev/guide/advanced/sfc.html). Nuxt также предлагает [переводы на уровне компонента](https://i18n.nuxtjs.org/docs/guide/per-component-translations), а Angular использует похожий паттерн через свои [Feature Modules](https://v17.angular.io/guide/feature-modules).

Даже в Flutter-приложении часто встречается следующий паттерн:

После интеграции nuxt/i18n в несколько моих проектов я пришел к однозначному выводу: это, безусловно, лучшее i18n-решение для JS-фреймворков.

Его «plug&play» настройка, загрузка пространств имен (namespaces) и встроенная маршрутизация, настоящее удовольствие в работе.

Однако у этого решения есть серьезная проблема: загруженные пространства имен не подвергаются «тришейкингу» (tree-shaking).

Несмотря на то, что JSON-файлы могут загружаться динамически для каждой локали, Nuxt в итоге объединяет их, что означает, что файл locale/zh/about.json загружается на всех страницах.

Если вы когда-либо использовали i18next или next-intl, вы, вероятно, знаете, что интернационализация часто замедляет процесс разработки.

Почему?

Недавно я перенёс Intlayer (решение для i18n) — монорепозиторий, состоящий из нескольких приложений (Next.js, Vite, React, design-system и т. д.) — с pnpm на Bun.

Кратко (TL;DR): если бы я знал заранее, я бы, вероятно, не делал этого.
Я думал, что это займёт пару часов. В итоге ушло около 20 часов.

Меня привлекло обещание «всё в одном» и впечатляющие показатели производительности.
Я попробовал, я собрал — всё билдилось молниеносно, круто.
Затем я сделал коммит… и столкнулся с первой проблемой.

Интернационализация (или i18n) — это одна из тех функций, которые кажутся необязательными, пока они действительно не понадобятся. Как только вы захотите выйти за пределы одного языка или региона, внезапно вашему коду приходится поддерживать несколько локалей, текст с направлением справа налево и культурно-специфичные форматы.

Если вы искали решения, то, скорее всего, уже встречали i18next или react-intl. Оба инструмента мощные, но у них есть свои недостатки: высокий порог входа, множество шаблонных JSON-файлов или сложная интеграция с TypeScript.

В этой статье мы разберём:

Всем привет! Хочу поделиться своим подходом к созданию чат-бота с функцией «умной документации» для проекта, над которым я работаю. **Я не являюсь экспертом в области ИИ, поэтому любые предложения и улучшения приветствуются!**

Цель этой статьи — **не** создавать очередной туториал по сборке чат-бота с OpenAI. Таких материалов уже достаточно.

Вместо этого я расскажу, как **индексировать документацию**, разделив её на **удобоваримые фрагменты**, создать для них **векторные представления (эмбеддинги)** с помощью OpenAI и выполнять **поиск по схожести**, чтобы находить наиболее релевантную информацию по пользовательскому запросу.

В моем случае документация представлена файлами в формате Markdown, но это может быть любой текст, объект базы данных и т.д.

---

## Зачем?

Потому что бывает сложно найти нужную информацию. Я хотел создать чат-бота, который может отвечать на вопросы по определенной теме и предоставлять соответствующий контекст из документации.

Такой ассистент может использоваться в разных сценариях:

- **Быстрые ответы на частые вопросы**

- **Поиск по документации как в Algolia**

- **Помощь пользователям в навигации по документации**

- **Анализ пользовательских вопросов и хранение их для анализа**

---

## Краткое содержание

Ниже приведены три основные части решения:

1. Чтение файлов документации

2. Индексация документации (разбиение, перекрытие, эмбеддинги)

3. Поиск по документации и интеграция с чат-ботом

---

## 1. Чтение файлов документации

Вместо того чтобы жестко прописывать текст, вы можете просканировать папку и найти все `.md` файлы с помощью `glob`.

If you’re building a multilingual React Native (or web) app, you’ve probably tried react-i18next, i18n-js, LinguiJS, or similar libraries.

But in every project, the same issues come up:

❌ Unused key-value pairs are never removed
❌ Content gets duplicated
❌ Ensuring format consistency across languages is painful
❌ i18next doesn’t generate TypeScript types by default – so t("my.key") won’t throw even if it’s been deleted
❌ Localization platforms like Lokalise or Locize get expensive fast

Frustrated by these challenges, I waited for a better solution... then decided to build one myself: Intlayer.

У вас есть контент на сайте? Хотели бы редактировать его визуально, без необходимости погружаться в код?

Intlayer Visual Editor – это бесплатный инструмент с открытым исходным кодом, который позволяет редактировать контент вашего веб-приложения прямо в визуальном интерфейсе.

Недавно мне понадобилось добавить поддержку нескольких языков в API на базе Express. Я решил поделиться кратким руководством для тех, кто хочет сделать свой бэкенд отвечающим переведенным контентом в зависимости от предпочтительного языка пользователя.