Как Papermark автоматизировал локализацию документации с Lingo.dev

Papermark — open-source платформа для обмена документами. Когда команда решила локализовать документацию, она столкнулась с проблемой, на которой стопорятся многие команды, создающие инструменты для разработчиков: корректно настроить i18n в приложении на Next.js оказалось сложнее, чем сам перевод.

Проблема настройки#

«Я перепробовала все возможные пакеты для автоматизации и самодельные инструменты, — вспоминает Iuliia Shnai, основатель Papermark. — Самая большая боль была даже не в самом переводе, а в том, чтобы правильно встроить i18n в структуру нашего приложения».

Это типичная история. Большинство инструментов локализации исходят из того, что i18n-инфраструктура уже есть. С переводом они помогают. А вот с конфигурацией, структурой файлов, обработкой MDX и пограничными случаями, которые зависят от фреймворка, — нет. Для open-source проекта с небольшой командой время инженеров, потраченное на настройку локализации, — это прямые издержки для продукта.

Файлы MDX — документация на Markdown со встроенными React-компонентами — добавляют ещё один уровень сложности. Стандартные i18n-инструменты работают с JSON-файлами локалей и простыми строками. А MDX-контент с интерполяцией компонентов, frontmatter и пользовательскими тегами требует совсем другого подхода.

Что изменилось#

Макс, основатель Lingo.dev, сам вышел на связь и помог настроить Next.js-проект Papermark. Реализация закрыла те пограничные случаи, на которых команда буксовала: обработку MDX-файлов, взаимодействие между next-intl и файловой структурой приложения, а также извлечение строк для перевода из документации с большим количеством компонентов.

«Реализация учла столько пограничных случаев, о которых мы даже не подумали, — говорит Shnai. — Было видно, что они глубоко разобрались во всех сложностях локализации, особенно когда речь идёт о MDX-файлах, которые были для нас одной из самых болезненных точек».

Уже в первый день были переведены 80 страниц документации. Движок локализации, настроенный с учётом терминологии продукта Papermark и подключённый к их репозиторию, автоматически обработал весь массив документации.

Как это работает сейчас#

Движок локализации Papermark срабатывает при каждом push кода. Когда появляется новая документация или обновляется существующий контент, движок автоматически переводит изменения. Инженеры пишут документацию на английском, а локализованные версии появляются без дополнительных действий.

Здесь важна сохранность состояния. Поскольку движок локализации сохраняет терминологию продукта Papermark от запроса к запросу, специфичные для продукта термины вроде «Data Room», «Link tracking» и «NDA flow» переводятся единообразно на всех языках. И первая страница документации, прошедшая через движок, и сотая используют один и тот же словарь продукта.

«Ноль постоянных инженерных усилий на переводы» — вот измеримый результат. Но его настоящая причина в том, что локализация стала частью инфраструктуры, а не регулярной задачей.

Результаты#

• 80 страниц документации переведены в первый день
• Ноль постоянных инженерных усилий на локализацию
• Автоматическая обработка сложной MDX-документации
• Непрерывный перевод при каждом push — для нового и обновлённого контента
• Единообразная терминология на всех языках

Для open-source проекта экономика имеет значение. Каждый час, не потраченный на поддержку локализации, — это час, который можно отдать продукту. Papermark продолжает развивать свой движок локализации, чтобы охватить и SEO-оптимизацию в разных локалях.