@intlayer/docs 7.5.12 → 7.5.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (197) hide show
  1. package/blog/uk/compiler_vs_declarative_i18n.md +224 -0
  2. package/blog/uk/i18n_using_next-i18next.md +1086 -0
  3. package/blog/uk/i18n_using_next-intl.md +760 -0
  4. package/blog/uk/index.md +69 -0
  5. package/blog/uk/internationalization_and_SEO.md +273 -0
  6. package/blog/uk/intlayer_with_i18next.md +211 -0
  7. package/blog/uk/intlayer_with_next-i18next.md +202 -0
  8. package/blog/uk/intlayer_with_next-intl.md +203 -0
  9. package/blog/uk/intlayer_with_react-i18next.md +200 -0
  10. package/blog/uk/intlayer_with_react-intl.md +202 -0
  11. package/blog/uk/intlayer_with_vue-i18n.md +206 -0
  12. package/blog/uk/l10n_platform_alternative/Lokalise.md +80 -0
  13. package/blog/uk/l10n_platform_alternative/crowdin.md +80 -0
  14. package/blog/uk/l10n_platform_alternative/phrase.md +78 -0
  15. package/blog/uk/list_i18n_technologies/CMS/drupal.md +143 -0
  16. package/blog/uk/list_i18n_technologies/CMS/wix.md +167 -0
  17. package/blog/uk/list_i18n_technologies/CMS/wordpress.md +189 -0
  18. package/blog/uk/list_i18n_technologies/frameworks/angular.md +125 -0
  19. package/blog/uk/list_i18n_technologies/frameworks/flutter.md +128 -0
  20. package/blog/uk/list_i18n_technologies/frameworks/react-native.md +217 -0
  21. package/blog/uk/list_i18n_technologies/frameworks/react.md +155 -0
  22. package/blog/uk/list_i18n_technologies/frameworks/svelte.md +145 -0
  23. package/blog/uk/list_i18n_technologies/frameworks/vue.md +144 -0
  24. package/blog/uk/next-i18next_vs_next-intl_vs_intlayer.md +1499 -0
  25. package/blog/uk/nextjs-multilingual-seo-comparison.md +360 -0
  26. package/blog/uk/rag_powered_documentation_assistant.md +288 -0
  27. package/blog/uk/react-i18next_vs_react-intl_vs_intlayer.md +164 -0
  28. package/blog/uk/vue-i18n_vs_intlayer.md +279 -0
  29. package/blog/uk/what_is_internationalization.md +167 -0
  30. package/dist/cjs/generated/frequentQuestions.entry.cjs +20 -0
  31. package/dist/cjs/generated/frequentQuestions.entry.cjs.map +1 -1
  32. package/dist/esm/generated/frequentQuestions.entry.mjs +20 -0
  33. package/dist/esm/generated/frequentQuestions.entry.mjs.map +1 -1
  34. package/dist/types/generated/frequentQuestions.entry.d.ts +1 -0
  35. package/dist/types/generated/frequentQuestions.entry.d.ts.map +1 -1
  36. package/docs/ar/configuration.md +6 -1
  37. package/docs/ar/dictionary/content_file.md +6 -1
  38. package/docs/de/configuration.md +6 -1
  39. package/docs/de/dictionary/content_file.md +6 -1
  40. package/docs/en/configuration.md +6 -1
  41. package/docs/en/dictionary/content_file.md +6 -1
  42. package/docs/en-GB/configuration.md +6 -1
  43. package/docs/en-GB/dictionary/content_file.md +3 -1
  44. package/docs/es/configuration.md +6 -1
  45. package/docs/es/dictionary/content_file.md +6 -1
  46. package/docs/fr/configuration.md +6 -1
  47. package/docs/fr/dictionary/content_file.md +3 -1
  48. package/docs/hi/configuration.md +6 -1
  49. package/docs/hi/dictionary/content_file.md +3 -1
  50. package/docs/id/configuration.md +6 -1
  51. package/docs/id/dictionary/content_file.md +3 -1
  52. package/docs/it/configuration.md +6 -1
  53. package/docs/it/dictionary/content_file.md +3 -1
  54. package/docs/ja/configuration.md +6 -1
  55. package/docs/ja/dictionary/content_file.md +3 -1
  56. package/docs/ko/configuration.md +6 -1
  57. package/docs/ko/dictionary/content_file.md +3 -1
  58. package/docs/pl/configuration.md +3 -1
  59. package/docs/pl/dictionary/content_file.md +3 -1
  60. package/docs/pt/configuration.md +6 -1
  61. package/docs/pt/dictionary/content_file.md +3 -1
  62. package/docs/ru/configuration.md +6 -1
  63. package/docs/ru/dictionary/content_file.md +6 -1
  64. package/docs/tr/configuration.md +6 -1
  65. package/docs/tr/dictionary/content_file.md +3 -1
  66. package/docs/uk/CI_CD.md +198 -0
  67. package/docs/uk/autoFill.md +307 -0
  68. package/docs/uk/bundle_optimization.md +185 -0
  69. package/docs/uk/cli/build.md +64 -0
  70. package/docs/uk/cli/ci.md +137 -0
  71. package/docs/uk/cli/configuration.md +63 -0
  72. package/docs/uk/cli/debug.md +46 -0
  73. package/docs/uk/cli/doc-review.md +43 -0
  74. package/docs/uk/cli/doc-translate.md +132 -0
  75. package/docs/uk/cli/editor.md +28 -0
  76. package/docs/uk/cli/fill.md +130 -0
  77. package/docs/uk/cli/index.md +190 -0
  78. package/docs/uk/cli/init.md +84 -0
  79. package/docs/uk/cli/list.md +90 -0
  80. package/docs/uk/cli/list_projects.md +128 -0
  81. package/docs/uk/cli/live.md +41 -0
  82. package/docs/uk/cli/login.md +157 -0
  83. package/docs/uk/cli/pull.md +78 -0
  84. package/docs/uk/cli/push.md +98 -0
  85. package/docs/uk/cli/sdk.md +71 -0
  86. package/docs/uk/cli/test.md +76 -0
  87. package/docs/uk/cli/transform.md +65 -0
  88. package/docs/uk/cli/version.md +24 -0
  89. package/docs/uk/cli/watch.md +37 -0
  90. package/docs/uk/configuration.md +742 -0
  91. package/docs/uk/dictionary/condition.md +237 -0
  92. package/docs/uk/dictionary/content_file.md +1134 -0
  93. package/docs/uk/dictionary/enumeration.md +245 -0
  94. package/docs/uk/dictionary/file.md +232 -0
  95. package/docs/uk/dictionary/function_fetching.md +212 -0
  96. package/docs/uk/dictionary/gender.md +273 -0
  97. package/docs/uk/dictionary/insertion.md +187 -0
  98. package/docs/uk/dictionary/markdown.md +383 -0
  99. package/docs/uk/dictionary/nesting.md +273 -0
  100. package/docs/uk/dictionary/translation.md +332 -0
  101. package/docs/uk/formatters.md +595 -0
  102. package/docs/uk/how_works_intlayer.md +256 -0
  103. package/docs/uk/index.md +175 -0
  104. package/docs/uk/interest_of_intlayer.md +297 -0
  105. package/docs/uk/intlayer_CMS.md +569 -0
  106. package/docs/uk/intlayer_visual_editor.md +292 -0
  107. package/docs/uk/intlayer_with_angular.md +710 -0
  108. package/docs/uk/intlayer_with_astro.md +256 -0
  109. package/docs/uk/intlayer_with_create_react_app.md +1258 -0
  110. package/docs/uk/intlayer_with_express.md +429 -0
  111. package/docs/uk/intlayer_with_fastify.md +446 -0
  112. package/docs/uk/intlayer_with_lynx+react.md +548 -0
  113. package/docs/uk/intlayer_with_nestjs.md +283 -0
  114. package/docs/uk/intlayer_with_next-i18next.md +640 -0
  115. package/docs/uk/intlayer_with_next-intl.md +456 -0
  116. package/docs/uk/intlayer_with_nextjs_page_router.md +1541 -0
  117. package/docs/uk/intlayer_with_nuxt.md +711 -0
  118. package/docs/uk/intlayer_with_react_router_v7.md +600 -0
  119. package/docs/uk/intlayer_with_react_router_v7_fs_routes.md +669 -0
  120. package/docs/uk/intlayer_with_svelte_kit.md +579 -0
  121. package/docs/uk/intlayer_with_tanstack.md +818 -0
  122. package/docs/uk/intlayer_with_vite+preact.md +1748 -0
  123. package/docs/uk/intlayer_with_vite+react.md +1449 -0
  124. package/docs/uk/intlayer_with_vite+solid.md +302 -0
  125. package/docs/uk/intlayer_with_vite+svelte.md +520 -0
  126. package/docs/uk/intlayer_with_vite+vue.md +1113 -0
  127. package/docs/uk/introduction.md +222 -0
  128. package/docs/uk/locale_mapper.md +242 -0
  129. package/docs/uk/mcp_server.md +211 -0
  130. package/docs/uk/packages/express-intlayer/t.md +465 -0
  131. package/docs/uk/packages/intlayer/getEnumeration.md +159 -0
  132. package/docs/uk/packages/intlayer/getHTMLTextDir.md +121 -0
  133. package/docs/uk/packages/intlayer/getLocaleLang.md +81 -0
  134. package/docs/uk/packages/intlayer/getLocaleName.md +135 -0
  135. package/docs/uk/packages/intlayer/getLocalizedUrl.md +338 -0
  136. package/docs/uk/packages/intlayer/getMultilingualUrls.md +359 -0
  137. package/docs/uk/packages/intlayer/getPathWithoutLocale.md +75 -0
  138. package/docs/uk/packages/intlayer/getPrefix.md +213 -0
  139. package/docs/uk/packages/intlayer/getTranslation.md +190 -0
  140. package/docs/uk/packages/intlayer/getTranslationContent.md +189 -0
  141. package/docs/uk/packages/next-intlayer/t.md +365 -0
  142. package/docs/uk/packages/next-intlayer/useDictionary.md +276 -0
  143. package/docs/uk/packages/next-intlayer/useIntlayer.md +263 -0
  144. package/docs/uk/packages/next-intlayer/useLocale.md +166 -0
  145. package/docs/uk/packages/react-intlayer/t.md +311 -0
  146. package/docs/uk/packages/react-intlayer/useDictionary.md +295 -0
  147. package/docs/uk/packages/react-intlayer/useI18n.md +250 -0
  148. package/docs/uk/packages/react-intlayer/useIntlayer.md +251 -0
  149. package/docs/uk/packages/react-intlayer/useLocale.md +210 -0
  150. package/docs/uk/per_locale_file.md +345 -0
  151. package/docs/uk/plugins/sync-json.md +398 -0
  152. package/docs/uk/readme.md +265 -0
  153. package/docs/uk/releases/v6.md +305 -0
  154. package/docs/uk/releases/v7.md +624 -0
  155. package/docs/uk/roadmap.md +346 -0
  156. package/docs/uk/testing.md +204 -0
  157. package/docs/vi/configuration.md +6 -1
  158. package/docs/vi/dictionary/content_file.md +6 -1
  159. package/docs/zh/configuration.md +6 -1
  160. package/docs/zh/dictionary/content_file.md +6 -1
  161. package/frequent_questions/ar/error-vite-env-only.md +77 -0
  162. package/frequent_questions/de/error-vite-env-only.md +77 -0
  163. package/frequent_questions/en/error-vite-env-only.md +77 -0
  164. package/frequent_questions/en-GB/error-vite-env-only.md +77 -0
  165. package/frequent_questions/es/error-vite-env-only.md +76 -0
  166. package/frequent_questions/fr/error-vite-env-only.md +77 -0
  167. package/frequent_questions/hi/error-vite-env-only.md +77 -0
  168. package/frequent_questions/id/error-vite-env-only.md +77 -0
  169. package/frequent_questions/it/error-vite-env-only.md +77 -0
  170. package/frequent_questions/ja/error-vite-env-only.md +77 -0
  171. package/frequent_questions/ko/error-vite-env-only.md +77 -0
  172. package/frequent_questions/pl/error-vite-env-only.md +77 -0
  173. package/frequent_questions/pt/error-vite-env-only.md +77 -0
  174. package/frequent_questions/ru/error-vite-env-only.md +77 -0
  175. package/frequent_questions/tr/error-vite-env-only.md +77 -0
  176. package/frequent_questions/uk/SSR_Next_no_[locale].md +104 -0
  177. package/frequent_questions/uk/array_as_content_declaration.md +72 -0
  178. package/frequent_questions/uk/build_dictionaries.md +58 -0
  179. package/frequent_questions/uk/build_error_CI_CD.md +74 -0
  180. package/frequent_questions/uk/bun_set_up.md +53 -0
  181. package/frequent_questions/uk/customized_locale_list.md +64 -0
  182. package/frequent_questions/uk/domain_routing.md +113 -0
  183. package/frequent_questions/uk/error-vite-env-only.md +77 -0
  184. package/frequent_questions/uk/esbuild_error.md +29 -0
  185. package/frequent_questions/uk/get_locale_cookie.md +142 -0
  186. package/frequent_questions/uk/intlayer_command_undefined.md +155 -0
  187. package/frequent_questions/uk/locale_incorect_in_url.md +73 -0
  188. package/frequent_questions/uk/package_version_error.md +181 -0
  189. package/frequent_questions/uk/static_rendering.md +44 -0
  190. package/frequent_questions/uk/translated_path_url.md +55 -0
  191. package/frequent_questions/uk/unknown_command.md +97 -0
  192. package/frequent_questions/vi/error-vite-env-only.md +77 -0
  193. package/frequent_questions/zh/error-vite-env-only.md +77 -0
  194. package/legal/uk/privacy_notice.md +83 -0
  195. package/legal/uk/terms_of_service.md +55 -0
  196. package/package.json +6 -6
  197. package/src/generated/frequentQuestions.entry.ts +20 -0
package/blog/uk/i18n_using_next-i18next.md ADDED
@@ -0,0 +1,1086 @@
1
+ ---
2
+ createdAt: 2025-11-01
3
+ updatedAt: 2025-11-01
4
+ title: Як інтернаціоналізувати ваш додаток Next.js за допомогою next-i18next
5
+ description: Налаштуйте i18n з next-i18next — найкращі практики та поради з SEO для багатомовних застосунків Next.js, що охоплюють інтернаціоналізацію, організацію контенту та технічне налаштування.
6
+ keywords:
7
+ - next-i18next
8
+ - i18next
9
+ - Інтернаціоналізація
10
+ - Блог
11
+ - Next.js
12
+ - JavaScript
13
+ - React
14
+ slugs:
15
+ - blog
16
+ - nextjs-internationalization-using-next-i18next
17
+ applicationTemplate: https://github.com/aymericzip/next-i18next-template
18
+ history:
19
+ - version: 7.0.6
20
+ date: 2025-11-01
21
+ changes: Початкова версія
22
+ ---
23
+
24
+ # Як інтернаціоналізувати ваш додаток Next.js за допомогою next-i18next у 2025 році
25
+
26
+ ## Зміст
27
+
28
+ <TOC/>
29
+
30
+ ## Що таке next-i18next?
31
+
32
+ **next-i18next** — популярне рішення для інтернаціоналізації (i18n) застосунків Next.js. Хоча оригінальний пакет `next-i18next` був розроблений для Pages Router, цей посібник показує, як реалізувати i18next з сучасним **App Router**, використовуючи безпосередньо `i18next` і `react-i18next`.
33
+
34
+ За допомогою цього підходу ви можете:
35
+
36
+ - **Організовувати переклади** за допомогою просторів імен (namespaces) (наприклад, `common.json`, `about.json`) для кращого керування контентом.
37
+ - **Завантажувати переклади ефективно** — завантажуючи лише ті простори імен, які потрібні для кожної сторінки, що зменшує розмір бандла.
38
+ - **Підтримувати як серверні, так і клієнтські компоненти** з правильною обробкою SSR та гідратації.
39
+ - **Забезпечити підтримку TypeScript** з типобезпечною конфігурацією локалі та ключів перекладу.
40
+ - **Оптимізуйте для SEO** з правильними метаданими, sitemap та інтернаціоналізацією robots.txt.
41
+
42
+ > Як альтернативу, ви також можете звернутися до [посібника next-intl](https://github.com/aymericzip/intlayer/blob/main/docs/blog/uk/i18n_using_next-intl.md), або безпосередньо використовуючи [Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/intlayer_with_nextjs_16.md).
43
+
44
+ > Див. порівняння у [next-i18next vs next-intl vs Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/blog/uk/next-i18next_vs_next-intl_vs_intlayer.md).
45
+
46
+ ## Практики, яких слід дотримуватися
47
+
48
+ Перш ніж перейти до реалізації, ось кілька практик, яких слід дотримуватися:
49
+
50
+ - **Встановіть атрибути HTML `lang` та `dir`**
51
+ У вашому layout обчисліть `dir` за допомогою `getLocaleDirection(locale)` і встановіть `<html lang={locale} dir={dir}>` для належної доступності та SEO.
52
+ - **Split messages by namespace**
53
+ Організуйте JSON-файли за локаллю та неймспейсом (наприклад, `common.json`, `about.json`), щоб завантажувати лише те, що потрібно.
54
+ - **Minimize client payload**
55
+ На сторінках надсилайте до `NextIntlClientProvider` лише потрібні неймспейси (наприклад, `pick(messages, ['common', 'about'])`).
56
+ - **Prefer static pages**
57
+ Віддавайте перевагу статичним сторінкам і використовуйте їх якомога частіше для кращої продуктивності та SEO.
58
+ - **I18n in server components**
59
+ Серверні компоненти, як-от pages або всі компоненти, що не позначені як `client`, є статичними і можуть бути попередньо зрендерені під час збірки. Тому нам доведеться передавати їм функції перекладу як пропси.
60
+ - **Set up TypeScript types**
61
+ Налаштуйте типи TypeScript для забезпечення типобезпеки у вашому додатку.
62
+ Для ваших локалей, щоб забезпечити безпеку типів у всьому вашому застосунку.
63
+ - **Проксі для перенаправлення**
64
+ Використовуйте proxy для обробки визначення локалі та маршрутизації й перенаправляйте користувача на відповідний URL з префіксом локалі.
65
+ - **Інтернаціоналізація ваших metadata, sitemap, robots.txt**
66
+ Інтернаціоналізуйте ваші metadata, sitemap, robots.txt за допомогою функції `generateMetadata`, наданої Next.js, щоб забезпечити кращу індексацію пошуковими системами для всіх локалей.
67
+ - **Локалізація посилань**
68
+ Локалізуйте посилання, використовуючи компонент `Link`, щоб перенаправляти користувача на відповідний URL з префіксом локалі. Це важливо для забезпечення індексації ваших сторінок у всіх локалях.
69
+ - **Автоматизація тестів та перекладів**
70
+ Автоматизація тестів та перекладів допомагає заощаджувати час на підтримку вашого багатомовного застосунку.
71
+
72
+ > Дивіться нашу документацію, яка містить усе, що потрібно знати про інтернаціоналізацію та SEO: [Інтернаціоналізація (i18n) з next-intl](https://github.com/aymericzip/intlayer/blob/main/docs/blog/uk/internationalization_and_SEO.md).
73
+
74
+ ---
75
+
76
+ ## Покроковий посібник з налаштування i18next у застосунку Next.js
77
+
78
+ <iframe
79
+ src="https://stackblitz.com/github/aymericzip/next-i18next-template?embed=1&ctl=1&file=src/app/i18n.ts"
80
+ className="m-auto overflow-hidden rounded-lg border-0 max-md:size-full max-md:h-[700px] md:aspect-16/9 md:w-full"
81
+ title="Демонстрація CodeSandbox — як інтернаціоналізувати ваш застосунок за допомогою Intlayer"
82
+ sandbox="allow-forms allow-modals allow-popups allow-presentation allow-same-origin allow-scripts"
83
+ loading="lazy"
84
+
85
+ > Дивіться [Шаблон застосунку](https://github.com/aymericzip/next-i18next-template) на GitHub.
86
+
87
+ Ось структура проєкту, яку ми створимо:
88
+
89
+ ```bash
90
+ .
91
+ ├── i18n.config.ts
92
+ └── src # Папка src необов'язкова
93
+ ├── locales
94
+ │ ├── en
95
+ │ │ ├── common.json
96
+ │ │ └── about.json
97
+ │ └── fr
98
+ │ ├── common.json
99
+ │ └── about.json
100
+ ├── types
101
+ │ └── i18next.d.ts
102
+ ├── app
103
+ │ ├── proxy.ts
104
+ │ ├── i18n
105
+ │ │ └── server.ts
106
+ │ └── [locale]
107
+ │ ├── layout.tsx
108
+ │ ├── (home) # / (група маршрутів, щоб не засмічувати всі сторінки повідомленнями головної)
109
+ │ │ ├── layout.tsx
110
+ │ │ └── page.tsx
111
+ │ └── about # /about (сторінка "about")
112
+ │ ├── layout.tsx
113
+ │ └── page.tsx
114
+ └── components
115
+ ├── I18nProvider.tsx
116
+ ├── ClientComponent.tsx
117
+ └── ServerComponent.tsx
118
+ ```
119
+
120
+ ### Крок 1: Встановіть залежності
121
+
122
+ Встановіть необхідні пакети за допомогою npm:
123
+
124
+ ```bash packageManager="npm"
125
+ npm install i18next react-i18next i18next-resources-to-backend
126
+ ```
127
+
128
+ ```bash packageManager="pnpm"
129
+ pnpm add i18next react-i18next i18next-resources-to-backend
130
+ ```
131
+
132
+ ```bash packageManager="yarn"
133
+ yarn add i18next react-i18next i18next-resources-to-backend
134
+ ```
135
+
136
+ - **i18next**: Основний фреймворк для інтернаціоналізації, який відповідає за завантаження та керування перекладами.
137
+ - **react-i18next**: React-байндинги для i18next, що надають хуки, такі як `useTranslation`, для клієнтських компонентів.
138
+ - **i18next-resources-to-backend**: Плагін, який дозволяє динамічно завантажувати файли перекладів, даючи змогу підвантажувати лише ті простори імен (namespaces), які потрібні.
139
+
140
+ ### Крок 2: Налаштуйте свій проєкт
141
+
142
+ Створіть файл конфігурації, щоб визначити підтримувані локалі, локаль за замовчуванням та допоміжні функції для локалізації URL. Цей файл слугує єдиним джерелом істини для вашої i18n-настройки та забезпечує безпечність типів у всьому застосунку.
143
+
144
+ Централізація конфігурації локалей запобігає невідповідностям і спрощує додавання або видалення локалей у майбутньому. Допоміжні функції забезпечують узгоджене формування URL для SEO та маршрутизації.
145
+
146
+ ```ts fileName="i18n.config.ts"
147
+ // Визначаємо підтримувані локалі як const-масив для безпечності типів
148
+ // Уточнення 'as const' змушує TypeScript виводити літеральні типи замість string[]
149
+ export const locales = ["en", "fr"] as const;
150
+
151
+ // Витягуємо тип Locale з масиву locales
152
+ // Це створює union-тип: "en" | "fr"
153
+ export type Locale = (typeof locales)[number];
154
+
155
+ // Мова за замовчуванням, яка використовується, коли мова не вказана
156
+ export const defaultLocale: Locale = "en";
157
+
158
+ // Мови з напрямком справа наліво, що потребують спеціальної обробки напрямку тексту
159
+ export const rtlLocales = ["ar", "he", "fa", "ur"] as const;
160
+
161
+ // Перевіряє, чи потребує мова напрямку RTL (справа наліво)
162
+ // Використовується для мов, таких як арабська, іврит, перська та урду
163
+ export const isRtl = (locale: string) =>
164
+ (rtlLocales as readonly string[]).includes(locale);
165
+
166
+ // Генерує локалізований шлях для заданої мови та шляху
167
+ // Шляхи для мови за замовчуванням не мають префікса (наприклад, "/about" замість "/en/about")
168
+ // Інші мови мають префікс (наприклад, "/fr/about")
169
+ export function localizedPath(locale: string, path: string) {
170
+ return locale === defaultLocale ? path : `/${locale}${path}`;
171
+ }
172
+
173
+ // Базовий URL для абсолютних адрес (використовується в sitemap, метаданих тощо)
174
+ const ORIGIN = "https://example.com";
175
+
176
+ // Генерує абсолютний URL з префіксом локалі
177
+ // Використовується для SEO-метаданих, sitemap'ів і канонічних URL
178
+ export function absoluteUrl(locale: string, path: string) {
179
+ return `${ORIGIN}${localizedPath(locale, path)}`;
180
+ }
181
+
182
+ // Використовується для встановлення cookie локалі в браузері
183
+ export function getCookie(locale: Locale) {
184
+ return [
185
+ `NEXT_LOCALE=${locale}`,
186
+ "Path=/",
187
+ `Max-Age=${60 * 60 * 24 * 365}`, // 1 рік
188
+ "SameSite=Lax",
189
+ ].join("; ");
190
+ }
191
+ ```
192
+
193
+ ### Крок 3: Централізація просторів імен перекладів
194
+
195
+ Створіть єдине джерело істини для кожного простору імен (namespace), який надає ваша аплікація. Повторне використання цього списку дозволяє синхронізувати код на сервері, клієнті та в інструментах і відкриває можливість суворої типізації для допоміжних функцій перекладу.
196
+
197
+ ```ts fileName="src/i18n.namespaces.ts"
198
+ export const namespaces = ["common", "about"] as const;
199
+
200
+ export type Namespace = (typeof namespaces)[number];
201
+ ```
202
+
203
+ ### Крок 4: Сувора типізація ключів перекладу за допомогою TypeScript
204
+
205
+ Розширіть `i18next`, щоб вказати на ваші канонічні мовні файли (зазвичай англійські). TypeScript потім виведе дійсні ключі для кожного простору імен, тож виклики `t()` перевіряються повністю.
206
+
207
+ ```ts fileName="src/types/i18next.d.ts"
208
+ import "i18next";
209
+
210
+ declare module "i18next" {
211
+ interface CustomTypeOptions {
212
+ defaultNS: "common";
213
+ resources: {
214
+ common: typeof import("@/locales/uk/common.json");
215
+ about: typeof import("@/locales/en/about.json");
216
+ };
217
+ }
218
+ }
219
+ ```
220
+
221
+ > Порада: Збережіть це оголошення в каталозі `src/types` (створіть папку, якщо вона не існує). Next.js вже включає `src` у `tsconfig.json`, тому розширення буде підхоплене автоматично. Якщо ні, додайте наступне до вашого файлу `tsconfig.json`:
222
+
223
+ ```json5 fileName="tsconfig.json"
224
+ {
225
+ "include": ["src/types/**/*.ts"],
226
+ }
227
+ ```
228
+
229
+ З цим налаштованим ви можете покладатися на автозаповнення та перевірки під час компіляції:
230
+
231
+ ```tsx
232
+ import { useTranslation, type TFunction } from "react-i18next";
233
+
234
+ const { t } = useTranslation("about");
235
+
236
+ // OK, типізовано: t("counter.increment")
237
+ // ПОМИЛКА, помилка компіляції: t("doesNotExist")
238
+ export type AboutTranslator = TFunction<"about">;
239
+ ```
240
+
241
+ ### Крок 5: Налаштування серверної ініціалізації i18n
242
+
243
+ Створіть функцію ініціалізації на сервері, яка завантажує переклади для серверних компонентів. Ця функція створює окремий екземпляр i18next для рендерингу на сервері, забезпечуючи завантаження перекладів перед рендерингом.
244
+
245
+ Серверні компоненти потребують власного екземпляра i18next, оскільки вони виконуються в іншому контексті, ніж клієнтські компоненти. Попереднє завантаження перекладів на сервері запобігає міганню неперекладеного вмісту та покращує SEO, гарантуючи, що пошукові системи бачать перекладений вміст.
246
+
247
+ ```ts fileName="src/app/i18n/server.ts"
248
+ import { createInstance } from "i18next";
249
+ import { initReactI18next } from "react-i18next/initReactI18next";
250
+ import resourcesToBackend from "i18next-resources-to-backend";
251
+ import { defaultLocale } from "@/i18n.config";
252
+ import { namespaces, type Namespace } from "@/i18n.namespaces";
253
+
254
+ // Налаштування динамічного завантаження ресурсів для i18next
255
+ // Ця функція динамічно імпортує JSON-файли перекладів на основі locale і namespace
256
+ // Приклад: locale="fr", namespace="about" -> імпортує "@/locales/fr/about.json"
257
+ const backend = resourcesToBackend(
258
+ (locale: string, namespace: string) =>
259
+ import(`@/locales/${locale}/${namespace}.json`)
260
+ );
261
+
262
+ const DEFAULT_NAMESPACES = [
263
+ namespaces[0],
264
+ ] as const satisfies readonly Namespace[];
265
+
266
+ /**
267
+ * Ініціалізує екземпляр i18next для рендерингу на сервері
268
+ *
269
+ * @returns Ініціалізований екземпляр i18next, готовий до використання на сервері
270
+ */
271
+ export async function initI18next(
272
+ locale: string,
273
+ ns: readonly Namespace[] = DEFAULT_NAMESPACES
274
+ ) {
275
+ // Створити новий екземпляр i18next (відокремлений від клієнтського екземпляру)
276
+ const i18n = createInstance();
277
+
278
+ // Ініціалізувати з інтеграцією для React та завантажувачем ресурсів (backend)
279
+ await i18n
280
+ .use(initReactI18next) // Увімкнути підтримку React hooks
281
+ .use(backend) // Увімкнути динамічне завантаження ресурсів
282
+ .init({
283
+ lng: locale,
284
+ fallbackLng: defaultLocale,
285
+ ns, // Завантажувати лише вказані простори імен для кращої продуктивності
286
+ defaultNS: "common", // Простір імен за замовчуванням, коли жоден не вказаний
287
+ interpolation: { escapeValue: false }, // Не екранувати HTML (React відповідає за захист від XSS)
288
+ react: { useSuspense: false }, // Вимкнути Suspense для сумісності з SSR
289
+ returnNull: false, // Повернути порожній рядок замість null для відсутніх ключів
290
+ initImmediate: false, // Відкласти ініціалізацію до завантаження ресурсів (швидший SSR)
291
+ });
292
+ return i18n;
293
+ }
294
+ ```
295
+
296
+ ### Крок 6: Створіть клієнтський провайдер i18n
297
+
298
+ Створіть клієнтський компонент-провайдер, який обгортає ваш додаток контекстом i18next. Цей провайдер отримує попередньо завантажені переклади з сервера, щоб запобігти мерехтінню неперекладеного вмісту (FOUC) та уникнути дублювання запитів.
299
+
300
+ Клієнтським компонентам потрібен власний екземпляр i18next, що працює в браузері. Приймаючи попередньо завантажені ресурси з сервера, ми забезпечуємо безшовну гідратацію та запобігаємо мерехтінню контенту. Провайдер також динамічно керує зміною локалі та завантаженням namespace.
301
+
302
+ ```tsx fileName="src/components/I18nProvider.tsx"
303
+ "use client";
304
+
305
+ import { useEffect, useState } from "react";
306
+ import { I18nextProvider } from "react-i18next";
307
+ import { createInstance, type ResourceLanguage } from "i18next";
308
+ import { initReactI18next } from "react-i18next/initReactI18next";
309
+ import resourcesToBackend from "i18next-resources-to-backend";
310
+ import { defaultLocale } from "@/i18n.config";
311
+ import { namespaces as allNamespaces, type Namespace } from "@/i18n.namespaces";
312
+
313
+ // Налаштування динамічного завантаження ресурсів на клієнті
314
+ // Та ж сама схема, що й на сервері, але цей екземпляр працює в браузері
315
+ const backend = resourcesToBackend(
316
+ (locale: string, namespace: string) =>
317
+ import(`@/locales/${locale}/${namespace}.json`)
318
+ );
319
+
320
+ type Props = {
321
+ locale: string;
322
+ namespaces?: readonly Namespace[];
323
+ // Попередньо завантажені ресурси з сервера (запобігає FOUC — мерехтінню неперекладеного вмісту)
324
+ // Формат: { namespace: translationBundle }
325
+ resources?: Record<Namespace, ResourceLanguage>;
326
+ children: React.ReactNode;
327
+ };
328
+
329
+ /**
330
+ * Клієнтський i18n provider, який обгортає додаток контекстом i18next
331
+ * Отримує попередньо завантажені ресурси з сервера, щоб уникнути повторного запиту перекладів
332
+ */
333
+ export default function I18nProvider({
334
+ locale,
335
+ namespaces = [allNamespaces[0]] as const,
336
+ resources,
337
+ children,
338
+ }: Props) {
339
+ // Створює інстанс i18n лише один раз за допомогою лінивої ініціалізації useState
340
+ // Це гарантує, що інстанс створюється лише один раз, а не при кожному рендері
341
+ const [i18n] = useState(() => {
342
+ const i18nInstance = createInstance();
343
+
344
+ i18nInstance
345
+ .use(initReactI18next)
346
+ .use(backend)
347
+ .init({
348
+ lng: locale,
349
+ fallbackLng: defaultLocale,
350
+ ns: namespaces,
351
+ // Якщо ресурси надані (з сервера), використовуйте їх, щоб уникнути запитів на клієнті
352
+ // Це запобігає FOUC і покращує початкову продуктивність завантаження
353
+ resources: resources ? { [locale]: resources } : undefined,
354
+ defaultNS: "common",
355
+ interpolation: { escapeValue: false },
356
+ react: { useSuspense: false },
357
+ returnNull: false, // Запобігає поверненню значень undefined
358
+ });
359
+
360
+ return i18nInstance;
361
+ });
362
+
363
+ // Оновлює мову, коли змінюється prop locale
364
+ useEffect(() => {
365
+ i18n.changeLanguage(locale);
366
+ }, [locale, i18n]);
367
+
368
+ // Переконується, що всі необхідні namespaces завантажені на клієнті
369
+ // Використання join("|") як залежності для правильного порівняння масивів
370
+ useEffect(() => {
371
+ i18n.loadNamespaces(namespaces);
372
+ }, [namespaces.join("|"), i18n]);
373
+
374
+ // Надати екземпляр i18n усім дочірнім компонентам через React context
375
+ return <I18nextProvider i18n={i18n}>{children}</I18nextProvider>;
376
+ }
377
+ ```
378
+
379
+ ### Крок 7: Визначення динамічних маршрутів локалей
380
+
381
+ Налаштуйте динамічну маршрутизацію для локалей, створивши директорію `[locale]` у вашій папці app. Це дозволяє Next.js обробляти маршрути залежно від локалі, де кожна локаль стає сегментом URL (наприклад, `/en/about`, `/fr/about`).
382
+
383
+ Використання динамічних маршрутів дозволяє Next.js генерувати статичні сторінки для всіх локалей під час збірки, що покращує продуктивність і SEO. Компонент layout встановлює HTML-атрибути `lang` та `dir` на основі локалі, що має вирішальне значення для доступності та розуміння сторінки пошуковими системами.
384
+
385
+ ```tsx fileName="src/app/[locale]/layout.tsx"
386
+ import type { ReactNode } from "react";
387
+ import { locales, defaultLocale, isRtl, type Locale } from "@/i18n.config";
388
+
389
+ // Вимкнути динамічні параметри — усі локалі повинні бути відомі на етапі збірки
390
+ // Це забезпечує статичну генерацію для всіх маршрутів локалей
391
+ export const dynamicParams = false;
392
+
393
+ /**
394
+ * Згенерувати статичні параметри для всіх локалей на етапі збірки
395
+ * Next.js буде попередньо рендерити сторінки для кожної локалі, що повернена тут
396
+ * Приклад: [{ locale: "en" }, { locale: "fr" }]
397
+ */
398
+ export function generateStaticParams() {
399
+ return locales.map((locale) => ({ locale }));
400
+ }
401
+
402
+ /**
403
+ * Кореневий layout-компонент, який обробляє атрибути HTML для конкретної локалі
404
+ * Встановлює атрибут lang і напрямок тексту (ltr/rtl) залежно від локалі
405
+ */
406
+ export default function LocaleLayout({
407
+ children,
408
+ params,
409
+ }: {
410
+ children: ReactNode;
411
+ params: { locale: string };
412
+ }) {
413
+ // Перевіряємо locale з параметрів URL
414
+ // Якщо вказано недійсну locale, використовуємо defaultLocale
415
+ const locale: Locale = (locales as readonly string[]).includes(params.locale)
416
+ ? (params.locale as any)
417
+ : defaultLocale;
418
+
419
+ // Визначаємо напрямок тексту залежно від locale
420
+ // Мови з написанням справа наліво (RTL), такі як арабська, потребують dir="rtl" для правильного відображення тексту
421
+ const dir = isRtl(locale) ? "rtl" : "ltr";
422
+
423
+ return (
424
+ <html lang={locale} dir={dir}>
425
+ <body>{children}</body>
426
+ </html>
427
+ );
428
+ }
429
+ ```
430
+
431
+ ### Крок 8: Створіть файли перекладів
432
+
433
+ Створіть JSON-файли для кожного locale та namespace. Така структура дозволяє логічно організувати переклади та завантажувати лише те, що потрібно для кожної сторінки.
434
+
435
+ Організація перекладів за неймспейсами (наприклад, `common.json`, `about.json`) дозволяє розділяти код (code splitting) і зменшувати розмір бандла. Ви завантажуєте лише переклади, потрібні для кожної сторінки, що покращує продуктивність.
436
+
437
+ ```json fileName="src/locales/en/common.json"
438
+ {
439
+ "appTitle": "Додаток Next.js i18n",
440
+ "appDescription": "Приклад додатку Next.js з інтернаціоналізацією за допомогою i18next"
441
+ }
442
+ ```
443
+
444
+ ```json fileName="src/locales/fr/common.json"
445
+ {
446
+ "appTitle": "Додаток Next.js i18n",
447
+ "appDescription": "Приклад додатку Next.js з інтернаціоналізацією за допомогою i18next"
448
+ }
449
+ ```
450
+
451
+ ```json fileName="src/locales/en/home.json"
452
+ {
453
+ "title": "Головна",
454
+ "description": "Опис головної сторінки",
455
+ "welcome": "Ласкаво просимо",
456
+ "greeting": "Привіт, світ!",
457
+ "aboutPage": "Сторінка «Про»",
458
+ "documentation": "Документація"
459
+ }
460
+ ```
461
+
462
+ ```json fileName="src/locales/fr/home.json"
463
+ {
464
+ "title": "Головна",
465
+ "description": "Опис головної сторінки",
466
+ "welcome": "Ласкаво просимо",
467
+ "greeting": "Привіт, світ!",
468
+ "aboutPage": "Сторінка «Про»",
469
+ "documentation": "Документація"
470
+ }
471
+ ```
472
+
473
+ ```json fileName="src/locales/en/about.json"
474
+ {
475
+ "title": "Про",
476
+ "description": "Опис сторінки «Про»",
477
+ "counter": {
478
+ "label": "Лічильник",
479
+ "increment": "Збільшити",
480
+ "description": "Натисніть кнопку, щоб збільшити лічильник"
481
+ }
482
+ }
483
+ ```
484
+
485
+ ```json fileName="src/locales/fr/about.json"
486
+ {
487
+ "title": "Про",
488
+ "description": "Опис сторінки «Про»",
489
+ "counter": {
490
+ "label": "Лічильник",
491
+ "increment": "Збільшити",
492
+ "description": "Натисніть кнопку, щоб збільшити лічильник"
493
+ }
494
+ }
495
+ ```
496
+
497
+ ### Крок 9: Використовуйте переклади на своїх сторінках
498
+
499
+ Створіть компонент сторінки, який ініціалізує i18next на сервері та передає переклади як серверним, так і клієнтським компонентам. Це гарантує завантаження перекладів перед рендерінгом і запобігає мерехтінню контенту.
500
+
501
+ Ініціалізація на сервері завантажує переклади до того, як сторінка буде відрендерена, що покращує SEO та запобігає FOUC (Flash of Unstyled Content). Передаючи попередньо завантажені ресурси провайдеру на клієнті, ми уникаємо повторних запитів і забезпечуємо плавну гідратацію.
502
+
503
+ ```tsx fileName="src/app/[locale]/about/index.tsx"
504
+ import I18nProvider from "@/components/I18nProvider";
505
+ import { initI18next } from "@/app/i18n/server";
506
+ import type { Locale } from "@/i18n.config";
507
+ import { namespaces as allNamespaces, type Namespace } from "@/i18n.namespaces";
508
+ import type { ResourceLanguage } from "i18next";
509
+ import ClientComponent from "@/components/ClientComponent";
510
+ import ServerComponent from "@/components/ServerComponent";
511
+
512
+ /**
513
+ * Серверна сторінка-компонент, яка ініціалізує i18n
514
+ * Попередньо завантажує переклади на сервері і передає їх клієнтським компонентам
515
+ */
516
+ export default async function AboutPage({
517
+ params: { locale },
518
+ }: {
519
+ params: { locale: Locale };
520
+ }) {
521
+ // Визначає, які простори імен перекладів потрібні цій сторінці
522
+ // Використовує централізований список для безпеки типів та автодоповнення
523
+ const pageNamespaces = allNamespaces;
524
+
525
+ // Ініціалізує i18next на сервері з потрібними просторами імен
526
+ // Це завантажує JSON-файли перекладів на стороні сервера
527
+ const i18n = await initI18next(locale, pageNamespaces);
528
+
529
+ // Отримати фіксовану функцію перекладу для простору імен "about"
530
+ // getFixedT фіксує простір імен, тож можна викликати t("title") замість t("about:title")
531
+ const tAbout = i18n.getFixedT(locale, "about");
532
+
533
+ // Витягнути бандли перекладів з екземпляра i18n
534
+ // Ці дані передаються в I18nProvider для гідратації i18n на клієнті
535
+ // Запобігає FOUC (Flash of Untranslated Content — миготінню неперекладеного вмісту) та уникає дубльованих запитів
536
+ const resources = Object.fromEntries(
537
+ pageNamespaces.map((ns) => [ns, i18n.getResourceBundle(locale, ns)])
538
+ ) satisfies Record<Namespace, ResourceLanguage>;
539
+
540
+ return (
541
+ <I18nProvider
542
+ locale={locale}
543
+ namespaces={pageNamespaces}
544
+ resources={resources}
545
+ >
546
+ <main>
547
+ <h1>{tAbout("title")}</h1>
548
+
549
+ <ClientComponent />
550
+ <ServerComponent t={tAbout} locale={locale} count={0} />
551
+ </main>
552
+ </I18nProvider>
553
+ );
554
+ }
555
+ ```
556
+
557
+ ### Крок 10: Використання перекладів у клієнтських компонентах
558
+
559
+ Клієнтські компоненти можуть використовувати хук `useTranslation` для доступу до перекладів. Цей хук надає доступ до функції перекладу та екземпляра i18n, що дозволяє перекладати вміст та отримувати інформацію про локаль.
560
+
561
+ Клієнтські компоненти потребують React-хуків для доступу до перекладів. Хук `useTranslation` органічно інтегрується з i18next і забезпечує реактивне оновлення при зміні локалі.
562
+
563
+ > Переконайтеся, що сторінка/провайдер містить лише ті простори імен (namespaces), які вам потрібні (наприклад, `about`).
564
+ > Якщо ви використовуєте React < 19, мемоізуйте важкі форматтери, наприклад `Intl.NumberFormat`.
565
+
566
+ ```tsx fileName="src/components/ClientComponent.tsx"
567
+ "use client";
568
+
569
+ import { useState } from "react";
570
+ import { useTranslation } from "react-i18next";
571
+
572
+ /**
573
+ * Приклад клієнтського компонента, що використовує React hooks для перекладів
574
+ * Можна використовувати хуки, такі як useState, useEffect та useTranslation
575
+ */
576
+ const ClientComponent = () => {
577
+ // Хук useTranslation надає доступ до функції перекладу та екземпляру i18n
578
+ // Вкажіть namespace, щоб завантажити лише переклади для неймспейсу "about"
579
+ const { t, i18n } = useTranslation("about");
580
+ const [count, setCount] = useState(0);
581
+
582
+ // Створюємо форматер чисел, враховуючий локаль
583
+ // i18n.language повертає поточну локаль (наприклад, "en", "fr")
584
+ // Intl.NumberFormat форматуватиме числа згідно з локальними правилами
585
+ const numberFormat = new Intl.NumberFormat(i18n.language);
586
+
587
+ return (
588
+ <div className="flex flex-col items-center gap-4">
589
+ {/* Форматувати число з урахуванням локалі */}
590
+ <p className="text-5xl font-bold text-white m-0">
591
+ {numberFormat.format(count)}
592
+ </p>
593
+ <button
594
+ type="button"
595
+ className="flex h-12 w-full items-center justify-center gap-2 rounded-full bg-foreground px-5 text-background transition-colors hover:bg-[#383838] dark:hover:bg-[#ccc] md:w-[158px]"
596
+ aria-label={t("counter.label")}
597
+ onClick={() => setCount((c) => c + 1)}
598
+ >
599
+ {t("counter.increment")}
600
+ </button>
601
+ </div>
602
+ );
603
+ };
604
+
605
+ export default ClientComponent;
606
+ ```
607
+
608
+ ### Крок 11: Використання перекладів у серверних компонентах
609
+
610
+ Серверні компоненти не можуть використовувати React hooks, тому вони отримують переклади через props від батьківських компонентів. Такий підхід робить серверні компоненти синхронними і дозволяє вкладати їх у клієнтські компоненти.
611
+
612
+ Серверні компоненти, які можуть бути вкладені в client boundaries, мають бути синхронними. Передаючи перекладені рядки та інформацію про локаль як props, ми уникаємо асинхронних операцій і забезпечуємо коректне рендерення.
613
+
614
+ ```tsx fileName="src/components/ServerComponent.tsx"
615
+ import type { TFunction } from "i18next";
616
+
617
+ type ServerComponentProps = {
618
+ // Функція перекладу, передана від батьківського серверного компонента
619
+ // Серверні компоненти не можуть використовувати hooks, тому переклади надходять через props
620
+ t: TFunction<"about">;
621
+ locale: string;
622
+ count: number;
623
+ };
624
+
625
+ /**
626
+ * Приклад Server component - отримує переклади через props
627
+ * Може бути вкладений у client components (async server components)
628
+ * Не може використовувати React hooks, тому всі дані повинні надходити через props або через асинхронні операції
629
+ */
630
+ const ServerComponent = ({ t, locale, count }: ServerComponentProps) => {
631
+ // Форматує число на сервері, використовуючи locale
632
+ // Це виконується на сервері під час SSR, що покращує початкове завантаження сторінки
633
+ const formatted = new Intl.NumberFormat(locale).format(count);
634
+
635
+ return (
636
+ <div className="flex flex-col items-center gap-4">
637
+ <p className="text-5xl font-bold text-white m-0">{formatted}</p>
638
+ {/* Використовує функцію перекладу, передану через props */}
639
+ <div className="flex flex-col items-center gap-2">
640
+ <span className="text-xl font-semibold text-white">
641
+ {t("counter.label")}
642
+ </span>
643
+ <span className="text-sm opacity-80 italic">
644
+ {t("counter.description")}
645
+ </span>
646
+ </div>
647
+ </div>
648
+ );
649
+ };
650
+
651
+ export default ServerComponent;
652
+ ```
653
+
654
+ ---
655
+
656
+ ### (Необов'язково) Крок 12: Змініть мову вашого контенту
657
+
658
+ Щоб змінити мову вашого контенту в Next.js, рекомендовано використовувати URL-адреси з префіксом локалі та компоненти Link від Next.js. Приклад нижче зчитує поточну локаль з маршруту, видаляє її з pathname і рендерить по одному посиланню для кожної доступної локалі.
659
+
660
+ ```tsx fileName="src/components/LocaleSwitcher.tsx"
661
+ "use client";
662
+
663
+ import Link from "next/link";
664
+ import { useParams, usePathname } from "next/navigation";
665
+ import { useMemo } from "react";
666
+ import { defaultLocale, getCookie, type Locale, locales } from "@/i18n.config";
667
+
668
+ export default function LocaleSwitcher() {
669
+ const params = useParams();
670
+ const pathname = usePathname();
671
+
672
+ const activeLocale = (params?.locale as Locale | undefined) ?? defaultLocale;
673
+
674
+ // Повертає локалізовану мітку для даної локалі або код локалі у верхньому регістрі
675
+ const getLocaleLabel = (locale: Locale): string => {
676
+ try {
677
+ // Використовує Intl.DisplayNames для отримання назви мови на відповідній локалі
678
+ const displayNames = new Intl.DisplayNames([locale], {
679
+ type: "language",
680
+ });
681
+ return displayNames.of(locale) ?? locale.toUpperCase();
682
+ } catch {
683
+ // Якщо Intl не підтримується або сталася помилка, повертаємо код локалі у верхньому регістрі
684
+ return locale.toUpperCase();
685
+ }
686
+ };
687
+
688
+ // Обчислює базовий шлях без префікса локалі
689
+ const basePath = useMemo(() => {
690
+ if (!pathname) return "/";
691
+
692
+ const segments = pathname.split("/").filter(Boolean);
693
+
694
+ if (segments.length === 0) return "/";
695
+
696
+ const maybeLocale = segments[0] as Locale;
697
+
698
+ if ((locales as readonly string[]).includes(maybeLocale)) {
699
+ const rest = segments.slice(1).join("/");
700
+ return rest ? `/${rest}` : "/";
701
+ }
702
+
703
+ return pathname;
704
+ }, [pathname]);
705
+
706
+ return (
707
+ <nav aria-label="Вибір мови">
708
+ {(locales as readonly Locale[]).map((locale) => {
709
+ const isActive = locale === activeLocale;
710
+
711
+ const href =
712
+ locale === defaultLocale ? basePath : `/${locale}${basePath}`;
713
+
714
+ return (
715
+ <Link
716
+ key={locale}
717
+ href={href}
718
+ aria-current={isActive ? "page" : undefined}
719
+ onClick={() => {
720
+ document.cookie = getCookie(locale);
721
+ }}
722
+ >
723
+ {getLocaleLabel(locale)}
724
+ </Link>
725
+ );
726
+ })}
727
+ </nav>
728
+ );
729
+ }
730
+ ```
731
+
732
+ ### (Необов'язково) Крок 13: Створіть локалізований компонент Link
733
+
734
+ Повторне використання локалізованих URL у вашому додатку зберігає навігацію послідовною та дружньою до SEO. Обгорніть `next/link` у невеликий хелпер, який додає префікс активної локалі до внутрішніх маршрутів, залишаючи зовнішні URL без змін.
735
+
736
+ ```tsx fileName="src/components/LocalizedLink.tsx"
737
+ "use client";
738
+
739
+ import NextLink, { type LinkProps } from "next/link";
740
+ import { useParams } from "next/navigation";
741
+ import type { ComponentProps, PropsWithChildren } from "react";
742
+ import {
743
+ defaultLocale,
744
+ type Locale,
745
+ locales,
746
+ localizedPath,
747
+ } from "@/i18n.config";
748
+
749
+ const isExternal = (href: string) => /^https?:\/\//.test(href);
750
+
751
+ type LocalizedLinkProps = PropsWithChildren<
752
+ Omit<LinkProps, "href"> &
753
+ Omit<ComponentProps<"a">, "href"> & { href: string; locale?: Locale }
754
+ >;
755
+
756
+ export default function LocalizedLink({
757
+ href,
758
+ locale,
759
+ children,
760
+ ...props
761
+ }: LocalizedLinkProps) {
762
+ const params = useParams();
763
+ const fallback = (params?.locale as Locale | undefined) ?? defaultLocale;
764
+ const normalizedLocale = (locales as readonly string[]).includes(fallback)
765
+ ? ((locale ?? fallback) as Locale)
766
+ : defaultLocale;
767
+
768
+ const normalizedPath = href.startsWith("/") ? href : `/${href}`;
769
+ const localizedHref = isExternal(href)
770
+ ? href
771
+ : localizedPath(normalizedLocale, normalizedPath);
772
+
773
+ return (
774
+ <NextLink href={localizedHref} {...props}>
775
+ {children}
776
+ </NextLink>
777
+ );
778
+ }
779
+ ```
780
+
781
+ > Порада: Оскільки `LocalizedLink` є drop-in replacement, мігруйте поступово, замінюючи імпорти та дозволяючи компоненту обробляти URL-адреси, специфічні для локалі.
782
+
783
+ ### (Необов'язково) Крок 14: Доступ до активної локалі всередині Server Actions
784
+
785
+ Server Actions часто потребують поточної локалі для email-розсилок, логування або інтеграцій зі сторонніми сервісами. Поєднайте cookie локалі, встановлене вашим проксі, із заголовком `Accept-Language` як fallback.
786
+
787
+ ```ts fileName="src/app/actions/get-current-locale.ts"
788
+ "use server";
789
+
790
+ import { cookies, headers } from "next/headers";
791
+ import { defaultLocale, locales, type Locale } from "@/i18n.config";
792
+
793
+ const KNOWN_LOCALES = new Set(locales as readonly string[]);
794
+
795
+ const normalize = (value: string | undefined): Locale | undefined => {
796
+ if (!value) return undefined;
797
+ const base = value.toLowerCase().split("-")[0];
798
+ return KNOWN_LOCALES.has(base) ? (base as Locale) : undefined;
799
+ };
800
+
801
+ export async function getCurrentLocale(): Promise<Locale> {
802
+ const cookieLocale = normalize(cookies().get("NEXT_LOCALE")?.value);
803
+
804
+ if (cookieLocale) return cookieLocale;
805
+
806
+ const headerLocale = normalize(headers().get("accept-language"));
807
+ return headerLocale ?? defaultLocale;
808
+ }
809
+
810
+ // Приклад Server Action, який використовує поточну локаль
811
+ export async function stuffFromServer(formData: FormData) {
812
+ const locale = await getCurrentLocale();
813
+
814
+ // Використовуйте локаль для локалізованих побічних ефектів (електронні листи, CRM тощо)
815
+ console.log(`Stuff from server with locale ${locale}`);
816
+ }
817
+ ```
818
+
819
+ > Оскільки цей хелпер спирається на cookies і headers Next.js, він працює в Route Handlers, Server Actions та інших серверних контекстах.
820
+
821
+ ### (Необов'язково) Крок 15: Інтернаціоналізуйте метадані
822
+
823
+ Переклад контенту важливий, але основна мета інтернаціоналізації — зробити ваш вебсайт більш помітним для світу. I18n — потужний інструмент для підвищення видимості сайту завдяки належному SEO.
824
+
825
+ Правильно інтернаціоналізовані метадані допомагають пошуковим системам зрозуміти, які мови доступні на ваших сторінках. Це включає встановлення meta-тегів hreflang, переклад заголовків і описів, а також забезпечення правильного налаштування canonical URLs для кожної локалі.
826
+
827
+ Ось список кращих практик щодо багатомовного SEO:
828
+
829
+ - Встановіть hreflang мета-теги у елементі `<head>`, щоб допомогти пошуковим системам зрозуміти, які мови доступні на сторінці
830
+ - Перелічіть усі переклади сторінки в sitemap.xml, використовуючи XML-схему `http://www.w3.org/1999/xhtml`
831
+ - Не забудьте виключити сторінки з префіксами з robots.txt (наприклад, `/dashboard`, `/fr/dashboard`, `/es/dashboard`)
832
+ - Використовуйте кастомний компонент Link для перенаправлення на найбільш локалізовану сторінку (наприклад, французькою `<a href="/fr/about">À propos</a>`)
833
+
834
+ Розробники часто забувають правильно посилатися на свої сторінки в різних локалях. Виправимо це:
835
+
836
+ ```tsx fileName="src/app/[locale]/about/layout.tsx"
837
+ import type { Metadata } from "next";
838
+ import {
839
+ locales,
840
+ defaultLocale,
841
+ localizedPath,
842
+ absoluteUrl,
843
+ } from "@/i18n.config";
844
+
845
+ /**
846
+ * Генерує SEO-метадані для кожної локалізованої версії сторінки
847
+ * Ця функція виконується для кожної локалі під час збірки
848
+ */
849
+ export async function generateMetadata({
850
+ params,
851
+ }: {
852
+ params: { locale: string };
853
+ }): Promise<Metadata> {
854
+ const { locale } = params;
855
+
856
+ // Динамічно імпортує файл перекладу для цієї локалі
857
+ // Використовується для отримання перекладеного заголовка та опису для метаданих
858
+ const messages = (await import(`@/locales/${locale}/about.json`)).default;
859
+
860
+ // Створює мапу hreflang для всіх локалей
861
+ // Допомагає пошуковим системам зрозуміти альтернативи мов
862
+ // Формат: { "en": "/about", "fr": "/fr/about" }
863
+ const languages = Object.fromEntries(
864
+ locales.map((locale) => [locale, localizedPath(locale, "/about")])
865
+ );
866
+
867
+ return {
868
+ title: messages.title,
869
+ description: messages.description,
870
+ alternates: {
871
+ // Канонічний URL для цієї локалі
872
+ canonical: absoluteUrl(locale, "/about"),
873
+ // Варіанти мов для SEO (теги hreflang)
874
+ // "x-default" вказує на версію за замовчуванням
875
+ languages: {
876
+ ...languages,
877
+ "x-default": absoluteUrl(defaultLocale, "/about"),
878
+ },
879
+ },
880
+ };
881
+ }
882
+
883
+ export default async function AboutPage() {
884
+ return <h1>Про</h1>;
885
+ }
886
+ ```
887
+
888
+ ### (Необов'язково) Крок 16: Інтернаціоналізуйте ваш Sitemap
889
+
890
+ Згенеруйте карту сайту (sitemap), яка включає всі локалізовані версії ваших сторінок. Це допомагає пошуковим системам знаходити та індексувати всі мовні версії вашого контенту.
891
+
892
+ Коректно інтернаціоналізована карта сайту гарантує, що пошукові системи можуть знайти та індексувати всі мовні версії ваших сторінок. Це підвищує видимість у міжнародних результатах пошуку.
893
+
894
+ ```ts fileName="src/app/sitemap.ts"
895
+ import type { MetadataRoute } from "next";
896
+ import { defaultLocale, locales } from "@/i18n";
897
+
898
+ const origin = "https://example.com";
899
+
900
+ const formatterLocalizedPath = (locale: string, path: string) =>
901
+ locale === defaultLocale ? `${origin}${path}` : `${origin}/${locale}${path}`;
902
+
903
+ /**
904
+ * Отримати мапу всіх локалей та їх локалізованих шляхів
905
+ *
906
+ * Приклад вихідних даних:
907
+ * {
908
+ * "en": "https://example.com",
909
+ * "fr": "https://example.com/fr",
910
+ * "es": "https://example.com/es",
911
+ * "x-default": "https://example.com"
912
+ * }
913
+ */
914
+ const getLocalizedMap = (path: string) =>
915
+ Object.fromEntries([
916
+ ...locales.map((locale) => [locale, formatterLocalizedPath(locale, path)]),
917
+ ["x-default", formatterLocalizedPath(defaultLocale, path)],
918
+ ]);
919
+
920
+ // Генерує sitemap з усіма мовними варіантами для кращого SEO
921
+ // Поле alternates повідомляє пошуковим системам про мовні версії
922
+ export default function sitemap(): MetadataRoute.Sitemap {
923
+ return [
924
+ {
925
+ url: formatterLocalizedPath(defaultLocale, "/"),
926
+ lastModified: new Date(),
927
+ changeFrequency: "monthly",
928
+ priority: 1.0,
929
+ alternates: { languages: getLocalizedMap("/") },
930
+ },
931
+ {
932
+ url: formatterLocalizedPath(defaultLocale, "/about"),
933
+ lastModified: new Date(),
934
+ changeFrequency: "monthly",
935
+ priority: 0.7,
936
+ alternates: { languages: getLocalizedMap("/about") },
937
+ },
938
+ ];
939
+ }
940
+ ```
941
+
942
+ ### (Необов'язково) Крок 17: Інтернаціоналізуйте ваш robots.txt
943
+
944
+ Створіть файл robots.txt, який правильно обробляє всі мовні версії ваших захищених маршрутів. Це гарантує, що пошукові системи не індексують сторінки адміністратора або панелі керування жодною мовою.
945
+
946
+ Правильна конфігурація robots.txt для всіх локалей запобігає індексації чутливих сторінок пошуковими системами будь-якою мовою. Це критично важливо для безпеки та конфіденційності.
947
+
948
+ ```ts fileName="src/app/robots.ts"
949
+ import type { MetadataRoute } from "next";
950
+ import { defaultLocale, locales } from "@/i18n";
951
+
952
+ const origin = "https://example.com";
953
+
954
+ // Генерує шляхи для всіх локалей (наприклад, /admin, /fr/admin, /es/admin)
955
+ const withAllLocales = (path: string) => [
956
+ path,
957
+ ...locales
958
+ .filter((locale) => locale !== defaultLocale)
959
+ .map((locale) => `/${locale}${path}`),
960
+ ];
961
+
962
+ const disallow = [...withAllLocales("/dashboard"), ...withAllLocales("/admin")];
963
+
964
+ export default function robots(): MetadataRoute.Robots {
965
+ return {
966
+ rules: { userAgent: "*", allow: ["/"], disallow },
967
+ host: origin,
968
+ sitemap: `${origin}/sitemap.xml`,
969
+ };
970
+ }
971
+ ```
972
+
973
+ ### (Необов'язково) Крок 18: Налаштуйте middleware для маршрутизації локалей
974
+
975
+ Створіть проксі, який автоматично визначає переважну локаль користувача та перенаправляє його на відповідний URL з префіксом локалі. Це покращує досвід користувача, відображаючи контент обраною мовою.
976
+
977
+ Middleware гарантує, що користувачі автоматично перенаправляються на свою переважну мову під час відвідування сайту. Воно також зберігає мовні вподобання користувача в cookie для майбутніх відвідувань.
978
+
979
+ ```ts fileName="src/proxy.ts"
980
+ import { NextResponse, type NextRequest } from "next/server";
981
+ import { defaultLocale, locales } from "@/i18n.config";
982
+
983
+ // Регекс для відповідності файлів з розширеннями (наприклад, .js, .css, .png)
984
+ // Використовується, щоб виключити статичні ресурси з маршрутизації за локаллю
985
+ const PUBLIC_FILE = /\.[^/]+$/;
986
+
987
+ /**
988
+ * Витягує локаль з заголовка Accept-Language
989
+ * Підтримує формати на кшталт "fr-CA", "en-US" тощо.
990
+ * Повертає локаль за замовчуванням, якщо мова браузера не підтримується
991
+ */
992
+ const pickLocale = (accept: string | null) => {
993
+ // Отримати першу мовну перевагу (наприклад, "fr-CA" з "fr-CA,en-US;q=0.9")
994
+ const raw = accept?.split(",")[0] ?? defaultLocale;
995
+ // Витягти базовий код мови (наприклад, "fr" з "fr-CA")
996
+ const base = raw.toLowerCase().split("-")[0];
997
+ // Перевірити, чи підтримується ця локаль; інакше використовувати локаль за замовчуванням
998
+ return (locales as readonly string[]).includes(base) ? base : defaultLocale;
999
+ };
1000
+
1001
+ /**
1002
+ * Проксі Next.js для визначення локалі та маршрутизації
1003
+ * Виконується для кожного запиту перед рендерингом сторінки
1004
+ * Автоматично перенаправляє на URL з префіксом локалі, коли це необхідно
1005
+ */
1006
+ export function proxy(request: NextRequest) {
1007
+ const { pathname } = request.nextUrl;
1008
+
1009
+ // Пропустити проксі для внутрішніх шляхів Next.js, API-роутів і статичних файлів
1010
+ // Ці шляхи не повинні мати префікс локалі
1011
+ if (
1012
+ pathname.startsWith("/_next") ||
1013
+ pathname.startsWith("/api") ||
1014
+ pathname.startsWith("/static") ||
1015
+ PUBLIC_FILE.test(pathname)
1016
+ ) {
1017
+ return;
1018
+ }
1019
+
1020
+ // Перевірити, чи URL вже містить префікс локалі
1021
+ // Приклад: "/fr/about" або "/en" повернуть true
1022
+ const hasLocale = (locales as readonly string[]).some(
1023
+ (locale) => pathname === `/${locale}` || pathname.startsWith(`/${locale}/`)
1024
+ );
1025
+
1026
+ // Якщо префікс локалі відсутній — визначаємо локаль і робимо перенаправлення
1027
+ if (!hasLocale) {
1028
+ // Спочатку намагаємося отримати локаль з cookie (налаштування користувача)
1029
+ const cookieLocale = request.cookies.get("NEXT_LOCALE")?.value;
1030
+
1031
+ // Використовуємо локаль з cookie, якщо вона дійсна; інакше визначаємо за заголовками браузера
1032
+ const locale =
1033
+ cookieLocale && (locales as readonly string[]).includes(cookieLocale)
1034
+ ? cookieLocale
1035
+ : pickLocale(request.headers.get("accept-language"));
1036
+
1037
+ // Клонуємо URL, щоб змінити pathname
1038
+ const url = request.nextUrl.clone();
1039
+ // Додаємо префікс локалі до pathname
1040
+ // Особливо обробляємо кореневий шлях, щоб уникнути подвійного слешу
1041
+ url.pathname = `/${locale}${pathname === "/" ? "" : pathname}`;
1042
+
1043
+ // Створити відповідь з перенаправленням і встановити cookie з локаллю
1044
+ const res = NextResponse.redirect(url);
1045
+ res.cookies.set("NEXT_LOCALE", locale, { path: "/" });
1046
+ return res;
1047
+ }
1048
+ }
1049
+
1050
+ export const config = {
1051
+ matcher: [
1052
+ // Відповідає всім шляхам, крім:
1053
+ // - API маршрути (/api/*)
1054
+ // - Внутрішні шляхи Next.js (/_next/*)
1055
+ // - Статичні файли (/static/*)
1056
+ // - Файли з розширеннями (.*\\..*)
1057
+ "/((?!api|_next|static|.*\\..*).*)",
1058
+ ],
1059
+ };
1060
+ ```
1061
+
1062
+ ### (Необов'язково) Крок 19: Автоматизуйте ваші переклади за допомогою Intlayer
1063
+
1064
+ Intlayer — це **безкоштовна** та **з відкритим вихідним кодом** бібліотека, створена для допомоги у процесі локалізації вашого застосунку. Поки i18next відповідає за завантаження та управління перекладами, Intlayer допомагає автоматизувати робочий процес перекладів.
1065
+
1066
+ Керування перекладами вручну може займати багато часу й бути схильним до помилок. Intlayer автоматизує тестування, генерацію та керування перекладами, заощаджуючи ваш час і забезпечуючи послідовність у всьому додатку.
1067
+
1068
+ Intlayer дозволяє вам:
1069
+
1070
+ - **Оголошуйте свій контент там, де вам зручно в codebase**
1071
+ Intlayer дозволяє оголошувати ваш контент там, де потрібно в codebase за допомогою файлів `.content.{ts|js|json}`. Це дає змогу краще організувати контент, забезпечуючи кращу читабельність та підтримуваність codebase.
1072
+
1073
+ - **Перевірка відсутніх перекладів**
1074
+ Intlayer надає функції тестування, які можна інтегрувати у ваш CI/CD pipeline або в модульні тести. Дізнайтеся більше про [тестування ваших перекладів](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/testing.md).
1075
+
1076
+ - **Автоматизуйте ваші переклади**,
1077
+ Intlayer надає CLI та розширення для VSCode для автоматизації ваших перекладів. Це можна інтегрувати у ваш CI/CD pipeline. Дізнайтеся більше про [автоматизацію перекладів](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/cli/index.md).
1078
+ Ви можете використовувати свій **власний API-ключ та AI-провайдера на ваш вибір**. Також він забезпечує контекстно-залежні переклади, див. [заповнення контенту](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/autoFill.md).
1079
+
1080
+ - **Підключення зовнішнього контенту**
1081
+ Intlayer дозволяє підключати ваш контент до зовнішньої системи керування контентом (CMS), щоб отримувати його оптимізовано та вставляти у ваші JSON-ресурси. Дізнайтеся більше про [отримання зовнішнього контенту](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/dictionary/function_fetching.md).
1082
+
1083
+ - **Візуальний редактор**
1084
+ Intlayer пропонує безкоштовний візуальний редактор для редагування вашого контенту. Дізнайтеся більше про [візуальне редагування ваших перекладів](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/intlayer_visual_editor.md).
1085
+
1086
+ І це ще не все. Щоб дізнатися про всі можливості, які надає Intlayer, будь ласка, перегляньте [документацію «Переваги Intlayer»](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/interest_of_intlayer.md).