Задайте питання та отримайте підсумок документа, вказавши цю сторінку та обраного вами постачальника штучного інтелекту
Історія версій
- Початкова версіяv7.0.001.11.2025
Вміст цієї сторінки перекладено за допомогою штучного інтелекту.
Переглянути останню версію оригінального вмісту англійськоюЯкщо у вас є ідея щодо покращення цієї документації, будь ласка, долучіться, надіславши pull request на GitHub.
Посилання на документацію на GitHubСкопіювати документацію у форматі Markdown в буфер обміну
Як інтернаціоналізувати ваш додаток Next.js за допомогою next-intl у 2025 році
Зміст
Що таке next-intl?
next-intl, популярна бібліотека для інтернаціоналізації (i18n), спеціально створена для Next.js App Router. Вона забезпечує зручний спосіб створення багатомовних додатків на Next.js з відмінною підтримкою TypeScript і вбудованими оптимізаціями.
Якщо бажаєте, також можете звернутися до посібника next-i18next, або безпосередньо використати Intlayer.
Див. порівняння у next-i18next vs next-intl vs Intlayer.
Практики, яких слід дотримуватися
Перш ніж приступити до реалізації, ось кілька практик, яких варто дотримуватись:
- Set HTML
langanddirattributes У вашому layout обчислюйтеdirза допомогоюgetLocaleDirection(locale)і встановлюйте<html lang={locale} dir={dir}>для коректної доступності та SEO. - Split messages by namespace
Організовуйте файли JSON за локаллю та namespace (наприклад,
common.json,about.json), щоб завантажувати лише те, що потрібно. - Minimize client payload
На сторінках надсилайте до
NextIntlClientProviderлише потрібні namespace (наприклад,pick(messages, ['common', 'about'])). - Prefer static pages Якнайчастіше використовуйте статичні сторінки для кращої продуктивності та SEO.
- I18n in server components
I18n у серверних компонентах
Серверні компоненти, наприклад сторінки або всі компоненти, які не позначені як
client, є статичними і можуть бути попередньо відрендерені під час збірки. Тому нам доведеться передавати функції перекладу їм як props. - Set up TypeScript types Налаштуйте типи TypeScript для ваших локалей, щоб забезпечити типобезпеку в усьому додатку.
- Proxy for redirection Використовуйте проксі для обробки визначення локалі та маршрутизації і перенаправлення користувача на відповідний URL з префіксом локалі.
- Internationalization of your metadata, sitemap, robots.txt
Інтернаціоналізуйте ваші метадані, sitemap, robots.txt, використовуючи функцію
generateMetadata, надану Next.js, щоб забезпечити краще індексування пошуковими системами у всіх локалях. - Localize Links
Локалізуйте посилання
Локалізуйте посилання, використовуючи компонент
Link, щоб перенаправляти користувача на URL із відповідним префіксом локалі. Це важливо для забезпечення індексації ваших сторінок у всіх локалях. - Автоматизуйте тести та переклади Автоматизація тестів і перекладів допомагає економити час на підтримці вашого багатомовного додатка.
Дивіться нашу документацію з переліком усього, що потрібно знати про інтернаціоналізацію та SEO: Інтернаціоналізація (i18n) з next-intl.
Покроковий посібник з налаштування next-intl у застосунку Next.js
Див. Шаблон застосунку на GitHub.
Ось структура проєкту, яку ми створимо:
Скопіюйте код у буфер обміну
Встановіть залежності
Встановіть необхідні пакети, використовуючи:
bashКопіювати кодСкопіюйте код у буфер обміну
- next-intl: Основна бібліотека інтернаціоналізації для Next.js App Router, яка надає хуки, server-функції та клієнтські провайдери для керування перекладами.
Налаштуйте ваш проєкт
Створіть файл конфігурації, який визначає підтримувані локалі та налаштовує конфігурацію запитів next-intl. Цей файл слугує єдиним джерелом правди для вашої налаштування i18n і забезпечує безпеку типів у всьому застосунку.
Централізація конфігурації локалей запобігає невідповідностям і полегшує додавання або видалення локалей у майбутньому. Функція
getRequestConfigвиконується для кожного запиту й завантажує лише ті переклади, які потрібні для конкретної сторінки, що дозволяє застосувати code-splitting і зменшити розмір бандла.src/i18n.tsКопіювати кодСкопіюйте код у буфер обміну
Визначте динамічні маршрути локалей
Налаштуйте динамічний роутинг для локалей, створивши директорію
[locale]у вашій папці app. Це дозволяє Next.js обробляти маршрутизацію за локаллю, де кожна локаль стає сегментом URL (наприклад,/en/about,/fr/about).Використання динамічних маршрутів дозволяє Next.js генерувати статичні сторінки для всіх локалей під час збірки, що покращує продуктивність і SEO. Компонент layout встановлює HTML-атрибути
langтаdirна основі локалі, що є критично важливим для доступності та правильного розуміння сторінки пошуковими системами.src/app/[locale]/layout.tsxКопіювати кодСкопіюйте код у буфер обміну
src/app/[locale]/about/page.tsxКопіювати кодСкопіюйте код у буфер обміну
Створіть файли перекладів
Створіть JSON-файли для кожної локалі та простору імен. Така структура дозволяє логічно організувати переклади та завантажувати лише те, що потрібно для кожної сторінки.
Організація перекладів за просторами імен (наприклад,
common.json,about.json) дозволяє робити code splitting і зменшувати розмір бандла. Ви завантажуєте лише переклади, потрібні для конкретної сторінки, що покращує продуктивність.locales/en/common.jsonКопіювати кодСкопіюйте код у буфер обміну
locales/fr/common.jsonКопіювати кодСкопіюйте код у буфер обміну
locales/en/about.jsonКопіювати кодСкопіюйте код у буфер обміну
locales/fr/about.jsonКопіювати кодСкопіюйте код у буфер обміну
Використання перекладів на ваших сторінках
Створіть компонент сторінки, який завантажує переклади на сервері та передає їх як серверним, так і клієнтським компонентам. Це гарантує, що переклади завантажені перед рендерингом і запобігає блиманню (content flashing).
Завантаження перекладів на сервері покращує SEO та запобігає FOUC (Flash of Untranslated Content). Використовуючи
pickдля відправки тільки необхідних просторів імен до клієнтського провайдера, ми мінімізуємо JavaScript-бандл, що відправляється в браузер.src/app/[locale]/about/page.tsxКопіювати кодСкопіюйте код у буфер обміну
Використання перекладів у клієнтських компонентах
Клієнтські компоненти можуть використовувати хуки
useTranslationsтаuseFormatterдля доступу до перекладів і функцій форматування. Ці хуки читають дані з контекстуNextIntlClientProvider.Клієнтські компоненти потребують React-хуків для доступу до перекладів. Хуки
useTranslationsтаuseFormatterбезшовно інтегруються з next-intl і забезпечують реактивні оновлення при зміні локалі.Не забудьте додати необхідні namespaces до client messages сторінки (включайте лише ті namespaces, які дійсно потрібні вашим клієнтським компонентам).
src/components/ClientComponent.tsxКопіювати кодСкопіюйте код у буфер обміну
Використання перекладів у серверних компонентах
Серверні компоненти не можуть використовувати React‑хуки, тому вони отримують переклади та функції форматування як props від батьківських компонентів. Такий підхід зберігає серверні компоненти синхронними й дозволяє вкладати їх усередину клієнтських компонентів.
Серверні компоненти, які можуть бути вкладені в клієнтські межі, мають бути синхронними. Передаючи перекладені рядки та відформатовані значення як props, ми уникаємо асинхронних операцій і забезпечуємо правильне рендерення. Попередньо обчисліть переклади та форматування в батьківському компоненті сторінки.
src/components/ServerComponent.tsxКопіювати кодСкопіюйте код у буфер обміну
У вашому page/layout використовуйте
getTranslationsтаgetFormatterзnext-intl/server, щоб попередньо обчислити переклади та форматування, а потім передайте їх як props серверним компонентам.Змініть мову вашого контенту
Необов'язковоЩоб змінити мову контенту за допомогою next-intl, рендерте посилання з урахуванням локалі (locale-aware links), які вказують на той самий pathname при перемиканні локалі. Провайдер автоматично переписує URL-адреси, тож вам потрібно лише націлитися на поточний маршрут.
src/components/LocaleSwitcher.tsxКопіювати кодСкопіюйте код у буфер обміну
Використовуйте локалізований компонент Link
Необов'язковоnext-intlнадає сабпакетnext-intl/navigation, який містить локалізований компонент Link, що автоматично застосовує активну локаль. Ми вже експортували його для вас у файлі@/i18n, тож ви можете використовувати його так:src/components/MyComponent.tsxКопіювати кодСкопіюйте код у буфер обміну
Отримання активної локалі всередині Server Actions
Необов'язковоServer Actions можуть зчитувати поточну локаль за допомогою
next-intl/server. Це корисно для надсилання локалізованих електронних листів або збереження мовних налаштувань разом із надісланими даними.src/app/actions/get-current-locale.tsКопіювати кодСкопіюйте код у буфер обміну
getLocaleчитає локаль, встановлену проксіnext-intl, тож функція працює у будь-якому місці на сервері: Route Handlers, Server Actions та edge functions.Інтернаціоналізуйте свої метадані
Необов'язковоПереклад контенту важливий, але головна мета інтернаціоналізації, зробити ваш вебсайт більш помітним у світі. I18n, неймовірний важіль для підвищення видимості вашого вебсайту за допомогою правильної SEO.
Коректно інтернаціоналізовані метадані допомагають пошуковим системам зрозуміти, якими мовами доступні ваші сторінки. Це включає встановлення meta-тегів hreflang, переклад заголовків і описів, а також забезпечення правильності canonical URL для кожної локалі.
src/app/[locale]/about/layout.tsxКопіювати кодСкопіюйте код у буфер обміну
Інтернаціоналізуйте свій sitemap
Необов'язковоСтворіть sitemap, який включає всі мовні версії ваших сторінок. Це допомагає пошуковим системам виявляти та індексувати всі мовні версії вашого контенту.
Правильно інтернаціоналізований sitemap гарантує, що пошукові системи зможуть знайти та індексувати всі мовні версії ваших сторінок. Це покращує видимість у міжнародних результатах пошуку.
src/app/sitemap.tsКопіювати кодСкопіюйте код у буфер обміну
Інтернаціоналізуйте ваш robots.txt
Необов'язковоСтворіть файл robots.txt, який правильно обробляє всі мовні версії ваших захищених маршрутів. Це гарантує, що пошукові системи не індексують сторінки admin або dashboard жодною мовою.
Правильна конфігурація robots.txt для всіх локалей запобігає індексації конфіденційних сторінок пошуковими системами, коли ваші маршрути відрізняються для кожної локалі.
src/app/robots.tsКопіювати кодСкопіюйте код у буфер обміну
Налаштування proxy для маршрутизації локалі
Необов'язковоСтворіть proxy, щоб автоматично визначати бажану користувачем локаль та перенаправляти його на відповідний URL з префіксом локалі. next-intl надає зручну функцію proxy, яка обробляє це автоматично.
Проксі забезпечує автоматичне перенаправлення користувачів на їхню пріоритетну мову під час відвідування сайту. Воно також зберігає мовні налаштування користувача для майбутніх відвідувань, покращуючи досвід користувача.
src/proxy.tsКопіювати кодСкопіюйте код у буфер обміну
Налаштуйте типи TypeScript для локалі
Необов'язковоНалаштування TypeScript допоможе отримати автозаповнення та типобезпеку для ваших ключів.
Для цього ви можете створити файл global.ts у корені вашого проєкту та додати наступний код:
global.tsКопіювати кодСкопіюйте код у буфер обміну
Цей код використовує Module Augmentation, щоб додати locales і messages до типу AppConfig з next-intl.
Автоматизуйте переклади за допомогою Intlayer
Необов'язковоIntlayer, це безкоштовна та відкрита бібліотека, створена для полегшення процесу локалізації у вашому застосунку. У той час як next-intl відповідає за завантаження та управління перекладами, Intlayer допомагає автоматизувати робочий процес перекладів.
Ручне керування перекладами може займати багато часу та бути схильним до помилок. Intlayer автоматизує тестування, генерацію та управління перекладами, заощаджуючи ваш час і забезпечуючи узгодженість у всьому застосунку.
Intlayer дозволить вам:
Оголошувати контент там, де вам зручно у вашій codebase
Intlayer дозволяє оголошувати контент там, де вам зручно в codebase, використовуючи файли.content.{ts|js|json}. Це забезпечує кращу організацію контенту, покращуючи читабельність та підтримуваність вашої codebase.Тестувати відсутні переклади Intlayer надає функції тестування, які можна інтегрувати у ваші CI/CD-пайплайни або модульні тести. Дізнайтеся більше про тестування ваших перекладів.
Автоматизуйте ваші переклади, Intlayer надає CLI і розширення для VSCode для автоматизації ваших перекладів. Це можна інтегрувати у ваш CI/CD-пайплайн. Дізнайтеся більше про автоматизацію ваших перекладів. Ви можете використовувати ваш власний API-ключ та постачальника AI на ваш вибір. Intlayer також забезпечує контекстно-залежні переклади, див. автозаповнення контенту.
Підключайте зовнішній контент Intlayer дозволяє підключати ваш контент до зовнішньої системи управління контентом (CMS), отримувати його оптимізовано та вставляти у ваші JSON-ресурси. Дізнайтеся більше про отримання зовнішнього контенту.
Візуальний редактор Intlayer пропонує безкоштовний візуальний редактор для редагування вашого контенту. Дізнайтеся більше про візуальне редагування ваших перекладів.
І це ще не все. Щоб ознайомитися з усіма можливостями, які надає Intlayer, зверніться до документації про переваги Intlayer.
Коментарі
Поки що немає коментарів. Будьте першим, хто поділиться своїми думками.