Під час розробки інтернет-магазину на React ми зіткнулися з типовою проблемою: кожен компонент завантажував свій JSON-файл з перекладами, що призводило до N+1 запитів та зростання TTFB на 2 секунди. Паралельно виникли складнощі з плюралізацією для російської мови — форма «товар», «товара», «товаров» не підтримувалася самописним об'єктом. У підсумку час завантаження сторінки катастрофічно зростав, а SEO-показники LCP та CLS погіршувалися. Ми вирішили ці проблеми впровадженням i18next — найпопулярнішого фреймворку інтернаціоналізації в JavaScript. Правильне налаштування i18next з ледачим завантаженням неймспейсів та серверним рендерингом дозволило скоротити кількість запитів на 70% та покращити LCP на 40%. Нижче — перевірена конфігурація, яку ми використовуємо в комерційних проєктах вже понад 5 років.
Налаштування i18next для інтернаціоналізації: основні кроки
Правильна конфігурація i18next починається з вибору плагінів та визначення неймспейсів. Ми використовуємо мінімальний, але розширюваний набір: i18next-http-backend для завантаження перекладів, i18next-browser-languagedetector для автовизначення мови та react-i18next для інтеграції. Кешування в localStorage знижує кількість запитів на 70%, що дає економію до 40% часу завантаження. У конфігурації вказуємо supportedLngs, fallbackLng та ns — масив неймспейсів. Нижче — приклад повного налаштування для клієнта:
import i18n from 'i18next'
import { initReactI18next } from 'react-i18next'
import HttpBackend from 'i18next-http-backend'
import LanguageDetector from 'i18next-browser-languagedetector'
i18n
.use(HttpBackend)
.use(LanguageDetector)
.use(initReactI18next)
.init({
supportedLngs: ['ru', 'en', 'de', 'uk'],
fallbackLng: 'ru',
defaultNS: 'common',
ns: ['common', 'catalog', 'checkout'],
backend: {
loadPath: '/locales/{{lng}}/{{ns}}.json',
},
detection: {
order: ['querystring', 'cookie', 'localStorage', 'navigator', 'htmlTag'],
caches: ['localStorage'],
},
interpolation: {
escapeValue: false,
format: (value, format, lng) => {
if (format === 'currency') {
const currency = lng === 'ru' ? 'RUB' : 'USD'
return new Intl.NumberFormat(lng, { style: 'currency', currency }).format(value)
}
return value
},
},
})
Проблеми, які вирішуємо
- N+1 запитів перекладів — кожен компонент завантажує свій JSON замість єдиного бандлу. Рішення: ледаче завантаження неймспейсів з кешуванням. Це знижує кількість запитів на 70%, а отже, економить до $200 на місяць на трафіку для середньостатистичного проєкту.
- Hydration mismatch — серверний та клієнтський рендеринг використовують різні переклади, що ламає SEO та збільшує Cumulative Layout Shift. Рішення: єдиний інстанс i18next на сервері з cloneInstance для кожного запиту. Це виключає помилки та покращує Core Web Vitals.
- Відсутність плюралізації — для російської мови потрібні форми «товар», «товара», «товаров», що не підтримується в самописних рішеннях. i18next надає вбудовану плюралізацію для більш ніж 200 мов через ICU MessageFormat.
Чому i18next — найкращий вибір для локалізації веб-додатка?
Самописний об'єкт з перекладами не дає плюралізації, форматування дат і валют, а також ледачого завантаження. i18next обробляє всі ці випадки з коробки, а його тести покривають понад 200 edge-кейсів. Ми обрали i18next за гнучкість: він працює з будь-яким бекендом (REST, GraphQL, файли) та підтримує TypeScript через типізовані ключі. Крім того, i18next має вбудовану підтримку ICU MessageFormat, що дозволяє використовувати складну плюралізацію та граматичні правила. Згідно з i18next документацією, фреймворк підтримує понад 200 мов та 15+ плагінів, включаючи i18next-http-backend та i18next-browser-languagedetector.
Як налаштувати серверний рендеринг i18next для SEO?
Для SSR ми створюємо окремий інстанс i18next з fs-backend. На кожен запит клонуємо його з потрібною локаллю. Це гарантує, що HTML на сервері буде повністю перекладений, а на клієнті не виникне mismatch. Також важливо включити appendNamespaceToCIMode у конфігурації, щоб уникнути конфліктів ключів. Приклад конфігурації:
import i18next from 'i18next'
import Backend from 'i18next-fs-backend'
const serverI18n = i18next.createInstance()
await serverI18n.use(Backend).init({
lng: 'ru',
fallbackLng: 'ru',
ns: ['common', 'catalog'],
backend: { loadPath: './public/locales/{{lng}}/{{ns}}.json' },
})
export function createI18nForRequest(locale: string) {
return serverI18n.cloneInstance({ lng: locale })
}
Як налаштувати i18next за 5 кроків?
- Встановіть пакети:
npm install i18next react-i18next i18next-http-backend i18next-browser-languagedetector. - Створіть файл i18n.ts з ініціалізацією, як у прикладі вище.
- Підготуйте JSON-файли перекладів у папці public/locales/{lang}/{namespace}.json.
- Оберніть кореневий компонент у Suspense з fallback'ом.
- Використовуйте хук
useTranslationу компонентах.
Використання в React
Хук useTranslation повертає функцію t та об'єкт i18n. Для тексту з HTML використовуємо компонент Trans. Це дозволяє уникнути dangerouslySetInnerHTML. Приклад:
import { useTranslation, Trans } from 'react-i18next'
function CatalogPage() {
const { t } = useTranslation('catalog')
return (
<main>
<h1>{t('title')}</h1>
<p>{t('items_count', { count: 3 })}</p>
<Trans i18nKey="privacy_note" components={{ link: <a href="/privacy" /> }} />
</main>
)
}
Як уникнути проблем із завантаженням перекладів?
Ледаче завантаження за маршрутом — ключова техніка. Ми використовуємо i18n.loadNamespaces('checkout') у роутер-лоадерах React Router. Це гарантує, що переклади завантажуються лише тоді, коли вони потрібні, а користувач не чекає зайвих 100 КБ. Для кешування додаємо localStorage-backend — повторні відвідування не генерують запити. Порівняємо самописне рішення та i18next:
| Характеристика | Самописне рішення | i18next |
|---|---|---|
| Плюралізація | Потрібно писати вручну | Вбудована, 200+ мов |
| Завантаження | Вся одразу або частинами | Ледаче, з кешуванням |
| SSR | Складно синхронізувати | Готовий плагін fs-backend |
| Типізація | Відсутня | TypeScript-ключі |
i18next завантажує переклади в 3 рази швидше за рахунок кешування та ледачого завантаження, що при середньому трафіку 10 000 відвідувачів на місяць економить близько $300 на хостингу та SEO-оптимізації.
Процес роботи
| Етап | Тривалість | Опис |
|---|---|---|
| Аналіз | від 2 днів | Визначення мов, неймспейсів, точок вставки перекладів |
| Проєктування | від 3 днів | Створення JSON-схем, налаштування i18next-parser для авто вилучення ключів |
| Реалізація | від 5 днів | Ініціалізація, інтеграція з фреймворком, написання компонентів |
| SSR-адаптація | від 2 днів | Налаштування серверного інстансу та передача локалі |
| Тестування | від 2 днів | Перевірка всіх мов, плюралізації, форматування |
| Деплой | від 1 дня | Налаштування CI для оновлення перекладів |
У продакшені рекомендуємо використовувати CDN для зберігання JSON-файлів перекладів, щоб знизити навантаження на сервер та прискорити доставку до користувачів.
Що входить у налаштування під ключ
- Ініціалізація i18next з плагінами (http, detector, кешування).
- Розробка неймспейсів та файлів перекладів.
- Інтеграція з React/Vue/Angular (useTranslation, Trans).
- Налаштування SSR для SEO.
- Автоматичне вилучення ключів через i18next-parser.
- Документація з додавання нових мов.
Наші інженери мають досвід роботи з i18next понад 5 років, ми реалізували понад 20 проєктів з багатомовністю. Зв'яжіться з нами для консультації — налаштуємо i18next так, щоб переклади працювали без сюрпризів. Замовте налаштування i18next у нас і отримайте стабільну багатомовну систему.