i18n в SPA — рабочий стек

Локализация SPA — это не «переведём строки». Это даты, числа, валюты, плюрализация, RTL, SEO. Что взять.

i18n в SPA — рабочий стек

Локализация веб-приложения начинается с фразы «переведём кнопки» и почти всегда оказывается шире. Кроме текстов интерфейса есть даты, числа и валюты, правила множественного числа, направление письма, контент в базе и SEO. Если думать обо всём этом с начала, второй язык добавляется за предсказуемый срок. Если нет — превращается в месяцы раскопок по коду.

i18n в SPA — рабочий стек
Полный пайплайн i18n — четыре звена, каждое со своими инструментами.

Что входит в локализацию

  • Тексты UI: кнопки, подписи, ошибки, письма и уведомления.
  • Контент: статьи, описания товаров, справка.
  • Даты и время в локальном формате и часовом поясе пользователя.
  • Числа, валюты, единицы измерения.
  • Плюрализация: 1 файл, 2 файла, 5 файлов.
  • RTL — для арабского и иврита.
  • SEO: отдельные адреса для языков и hreflang.

Рабочий стек

  • react-i18next или next-intl — для строк интерфейса. Первый универсален для любого React-приложения, второй удобен в Next.js и работает с серверными компонентами.
  • Intl API, встроенный в браузеры и Node.js, — для дат, чисел, валют, относительного времени («3 дня назад») и правил плюрализации. Тянуть для этого тяжёлые библиотеки не нужно. Moment.js, например, сами авторы перевели в режим поддержки и советуют альтернативы.
  • ICU MessageFormat — для плюрализации и подстановок внутри фраз.
  • Контентные переводы — в базе или CMS, а не в JS-бандле. Описание товара на пяти языках не должно грузиться в браузер каждому пользователю.

Ключи переводов называйте по смыслу и месту, а не по тексту: checkout.submit, а не «Оформить заказ». Текст поменяется, а ключ останется, и не придётся искать его по всему коду. И сразу задайте язык по умолчанию для недостающих переводов, чтобы пользователь видел хотя бы исходную фразу, а не пустое место.

Плюрализация: почему русский ломает английские правила

В английском две формы: one и other. В русском — one (1, 21, 101), few (2–4, 22–24), many (5–20, 25–30) и other для дробных. Строка вида count === 1 ? 'файл' : 'файлов' ошибётся на «2 файлов» и «21 файлов». Правильно — описывать все формы и отдавать выбор движку, который опирается на Intl.PluralRules:

{count, plural,
  one {# файл}
  few {# файла}
  many {# файлов}
  other {# файла}
}

Переводчик видит фразу целиком и может переставить слова, как требует его язык. Склеивать фразу из кусков в коде («Найдено» + n + «товаров») нельзя: в другом языке порядок слов другой.

Даты, числа и деньги

Храните время в UTC, а форматируйте в момент показа через Intl.DateTimeFormat с локалью и часовым поясом пользователя. Числа и валюты — через Intl.NumberFormat: он сам поставит пробел или запятую в разрядах и правильный символ валюты. Сумма и валюта хранятся вместе, а форматирование — дело интерфейса.

Вёрстка: длина строк и RTL

Русский и немецкий текст часто длиннее английского, и кнопка, свёрстанная впритык под «Save», не вместит «Сохранить изменения». Закладывайте запас по ширине и проверяйте интерфейс с псевдолокализацией — когда строки автоматически удлиняются и обрамляются символами, сразу видно, что обрезается и что осталось захардкоженным.

Для RTL используйте логические CSS-свойства: margin-inline-start вместо margin-left, padding-inline-end вместо padding-right. Тогда смена dir="rtl" на корневом элементе разворачивает вёрстку почти без отдельных стилей.

SEO многоязычного SPA

Если язык переключается только в браузере, а адрес не меняется, поисковики увидят одну версию. Нужны отдельные URL для языков (/en/...), серверный рендеринг или пре-рендер, чтобы контент был в HTML, и взаимные ссылки hreflang между языковыми версиями плюс x-default. Не перенаправляйте автоматически по языку браузера: робот придёт с одним языком и не увидит остальные. Лучше предложить переключение баннером.

Что обычно ломается

  • Строки, захардкоженные в JSX. Проект стартовал без i18n, а потом их приходится вылавливать по всему коду. Подключайте библиотеку с первого дня, даже если язык пока один.
  • Английские правила плюрализации, применённые к русскому.
  • Ошибки в hreflang: ссылки не взаимные, ведут на редиректы или на закрытые от индексации страницы.
  • Все переводы в одном огромном JSON, который грузится целиком. Делите на пространства имён по разделам и подгружайте лениво.
  • Нет процесса перевода. Разработчик добавил ключ, перевод забыли, и в интерфейсе висит checkout.button.submit. Помогают проверка недостающих ключей в CI и система управления переводами, куда новые строки попадают автоматически.

Многоязычные приложения проектируем в рамках разработки веб-приложений, а для многоязычного контента часто подходит headless CMS, где у каждой записи есть языковые версии.

Если нужно добавить второй язык в существующее приложение, напишите в Telegram или MAX, оценим объём работ.

Разработка веб-приложения
Услуга по теме — обсудим ваш проект.

Есть задача по теме? Напишите — вернёмся с оценкой и сроками.

Написать в Telegram → Написать в MAX