@intlayer/docs 7.5.11 → 7.5.13

package/docs/uk/cli/transform.md

@@ -0,0 +1,65 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: Трансформувати компоненти
+description: Дізнайтеся, як трансформувати існуючі компоненти для використання Intlayer.
+keywords:
+  - Трансформація
+  - Компоненти
+  - Міграція
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - transform
+---
+
+# Трансформувати компоненти
+
+```bash
+npx intlayer transform
+```
+
+Ця команда аналізує ваші файли коду, щоб допомогти перенести існуючі компоненти на Intlayer. Вона підтримує інтерактивний вибір файлів або вказання конкретних файлів.
+
+## Аліаси:
+
+- `npx intlayer trans`
+
+## Параметри:
+
+**Опції вибору файлів:**
+
+- **`-f, --file [files...]`**: Список конкретних файлів для трансформації. Якщо не вказано, CLI просканує файли, що відповідають шаблону (`**/*.{tsx,jsx,vue,svelte,ts,js}`) і запропонує вам вибрати, які з них трансформувати.
+
+  > Приклад: `npx intlayer transform -f src/components/MyComponent.tsx`
+
+**Параметри виводу:**
+
+- **`-o, --output-content-declarations [outputContentDeclarations]`**: Каталог для збереження згенерованих файлів декларацій контенту.
+
+  > Приклад: `npx intlayer transform -o src/content`
+
+- **`--code-only`**: Трансформувати лише код компоненту (не записувати декларацію контенту).
+
+  > Приклад: `npx intlayer transform --code-only`
+
+- **`--declaration-only`**: Лише згенерувати декларацію контенту (не переписувати компонент).
+
+  > Приклад: `npx intlayer transform --declaration-only`
+
+**Параметри конфігурації:**
+
+- **`--base-dir`**: Вказати базовий каталог для проєкту.
+- **`--env`**: Вказати середовище.
+- **`--env-file`**: Надати власний файл середовища.
+- **`--verbose`**: Увімкнути детальне логування.
+
+**Необхідні плагіни:**
+
+Команда transform працює без додаткових плагінів для файлів TypeScript / JSX. Однак для проектів на Vue та Svelte потрібно встановити наступні плагіни:
+
+- **`@intlayer/vue-transformer`**: Для файлів Vue.
+- **`@intlayer/svelte-transformer`**: Для файлів Svelte.

package/docs/uk/cli/version.md

@@ -0,0 +1,24 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: Перевірка версії CLI
+description: Дізнайтеся, як перевірити встановлену версію Intlayer CLI.
+keywords:
+  - Версія
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - version
+---
+
+# Перевірка версії CLI
+
+```bash
+npx intlayer --version
+npx intlayer version
+```
+
+Обидві команди виводять встановлену версію Intlayer CLI.

package/docs/uk/cli/watch.md

@@ -0,0 +1,37 @@
+---
+createdAt: 2024-08-11
+updatedAt: 2025-11-22
+title: Відстеження словників
+description: Дізнайтеся, як відстежувати зміни у ваших файлах декларації контенту та автоматично створювати словники.
+keywords:
+  - Відстеження
+  - Словники
+  - CLI
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - cli
+  - watch
+---
+
+# Відстеження словників
+
+```bash
+npx intlayer watch
+```
+
+Ця команда відстежуватиме зміни у ваших файлах декларації контенту та автоматично створюватиме словники в каталозі `.intlayer`.
+Ця команда еквівалентна `npx intlayer build --watch --skip-prepare`.
+
+## Псевдоніми:
+
+- `npx intlayer dictionaries watch`
+- `npx intlayer dictionary watch`
+- `npx intlayer dic watch`
+
+## Аргументи:
+
+- **`--with`**: Запускає команду паралельно з відстеженням.
+
+  > Приклад: `npx intlayer watch --with "next dev --turbopack"`

package/docs/uk/compiler.md

@@ -0,0 +1,133 @@
+---
+createdAt: 2025-09-09
+updatedAt: 2025-09-09
+title: Intlayer Compiler | Автоматизоване витягування контенту для i18n
+description: Автоматизуйте процес інтернаціоналізації за допомогою Intlayer Compiler. Витягуйте контент безпосередньо з ваших компонентів для швидшого та ефективнішого i18n у Vite, Next.js та інших.
+keywords:
+  - Intlayer
+  - Compiler
+  - Інтернаціоналізація
+  - i18n
+  - Автоматизація
+  - Екстракція
+  - Швидкість
+  - Vite
+  - Next.js
+  - React
+  - Vue
+  - Svelte
+slugs:
+  - doc
+  - compiler
+history:
+  - version: 7.3.1
+    date: 2025-11-27
+    changes: Випуск компілятора
+---
+
+# Intlayer Compiler | Автоматизоване витягування контенту для i18n
+
+## Що таке Intlayer Compiler?
+
+The **Intlayer Compiler** — потужний інструмент, створений для автоматизації процесу інтернаціоналізації (i18n) у ваших додатках. Він сканує ваш вихідний код (JSX, TSX, Vue, Svelte) на наявність декларацій контенту, витягує їх і автоматично генерує необхідні файли словників. Це дозволяє зберігати контент поруч із компонентами, у той час як Intlayer займається керуванням та синхронізацією ваших словників.
+
+## Чому використовувати Intlayer Compiler?
+
+- **Automation**: Усуває ручне копіювання та вставляння контенту у словники.
+- **Speed**: Оптимізоване витягування контенту, яке забезпечує швидкість процесу збірки.
+- **Developer Experience**: Тримайте декларації контенту там, де вони використовуються, що покращує підтримуваність.
+- **Live Updates**: Підтримує Hot Module Replacement (HMR) для миттєвого зворотного зв'язку під час розробки.
+
+Див. публікацію в блозі [Compiler vs. Declarative i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/uk/compiler_vs_declarative_i18n.md) для детальнішого порівняння.
+
+## Чому не використовувати Intlayer Compiler?
+
+Хоча компілятор надає відмінний досвід «just works», він також запроваджує певні компроміси, про які слід знати:
+
+- **Heuristic ambiguity**: Компилятор має вгадувати, який контент призначений для користувача, а що — логіка додатка (наприклад, `className="active"`, коди статусу, ідентифікатори продуктів). У складних кодових базах це може призводити до хибних спрацьовувань або пропущених рядків, що вимагатимуть ручних анотацій та винятків.
+- **Static-only extraction**: Екстракція на основі компілятора спирається на статичний аналіз. Рядки, які існують лише під час виконання (коди помилок API, поля CMS тощо), не можуть бути виявлені або перекладені лише компілятором, тому вам усе одно потрібна додаткова стратегія i18n на рівні виконання.
+
+Для більш глибокого архітектурного порівняння див. публікацію в блозі [Compiler vs. Declarative i18n](https://github.com/aymericzip/intlayer/blob/main/docs/blog/uk/compiler_vs_declarative_i18n.md).
+
+Як альтернативу, щоб автоматизувати ваш процес i18n і зберегти повний контроль над контентом, Intlayer також надає команду автоматичної екстракції `intlayer transform` (див. [Документація CLI](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/cli/transform.md)), або команду `Intlayer: extract content to Dictionary` з розширення Intlayer для VS Code (див. [Документація розширення VS Code](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/vs_code_extension.md)).
+
+## Використання
+
+### Vite
+
+Для додатків на базі Vite (React, Vue, Svelte тощо) найпростіший спосіб використовувати компілятор — через плагін `vite-intlayer`.
+
+#### Встановлення
+
+```bash
+npm install vite-intlayer
+```
+
+#### Налаштування
+
+Оновіть ваш `vite.config.ts`, щоб включити плагін `intlayerCompiler`:
+
+```ts fileName="vite.config.ts"
+import { defineConfig } from "vite";
+import { intlayer, intlayerCompiler } from "vite-intlayer";
+
+export default defineConfig({
+  plugins: [
+    intlayer(),
+    intlayerCompiler(), // Додає плагін компілятора
+  ],
+});
+```
+
+#### Підтримка фреймворків
+
+Плагін Vite автоматично визначає та обробляє різні типи файлів:
+
+- **React / JSX / TSX**: Обробляються нативно.
+- **Vue**: Потребує `@intlayer/vue-compiler`.
+- **Svelte**: Потребує `@intlayer/svelte-compiler`.
+
+Переконайтеся, що встановили відповідний пакет компілятора для вашого фреймворку:
+
+```bash
+# Для Vue
+npm install @intlayer/vue-compiler
+
+# Для Svelte
+npm install @intlayer/svelte-compiler
+```
+
+### Next.js (Babel)
+
+Для Next.js або інших додатків на базі Webpack, що використовують Babel, ви можете налаштувати компілятор за допомогою плагіна `@intlayer/babel`.
+
+#### Встановлення
+
+```bash
+npm install @intlayer/babel
+```
+
+#### Конфігурація
+
+Оновіть ваш `babel.config.js` (або `babel.config.json`), щоб додати плагін для екстракції. Ми надаємо хелпер `getExtractPluginOptions`, який автоматично завантажує вашу конфігурацію Intlayer.
+
+```js fileName="babel.config.js"
+const {
+  intlayerExtractBabelPlugin,
+  intlayerOptimizeBabelPlugin,
+  getExtractPluginOptions,
+  getOptimizePluginOptions,
+} = require("@intlayer/babel");
+
+module.exports = {
+  presets: ["next/babel"],
+  plugins: [
+    // Витягує контент з компонентів у словники
+    [intlayerExtractBabelPlugin, getExtractPluginOptions()],
+    // Оптимізує імпорти, замінюючи useIntlayer на прямі імпорти словників
+    [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()],
+  ],
+};
+```
+
+Ця конфігурація гарантує, що контент, оголошений у ваших компонентах, автоматично витягується й використовується для генерації словників під час процесу збірки.

package/docs/uk/component_i18n.md

@@ -0,0 +1,194 @@
+---
+createdAt: 2024-03-07
+updatedAt: 2025-09-30
+title: Зробити компонент багатомовним (i18n) у React і Next.js
+description: Дізнайтеся, як оголошувати та отримувати локалізований вміст для створення багатомовного компонента React або Next.js за допомогою Intlayer.
+keywords:
+  - i18n
+  - component
+  - react
+  - multilingual
+  - next.js
+  - intlayer
+slugs:
+  - doc
+  - component
+  - i18n
+applicationTemplate: https://github.com/aymericzip/intlayer-vite-react-template
+youtubeVideo: https://www.youtube.com/watch?v=dS9L7uJeak4
+---
+
+# Як зробити компонент багатомовним (i18n) за допомогою Intlayer
+
+У цьому посібнику показано мінімальні кроки, щоб зробити UI-компонент багатомовним у двох поширених налаштуваннях:
+
+- React (Vite/SPA)
+- Next.js (App Router)
+
+Спочатку ви оголосите свій вміст, а потім отримаєте його у своєму компоненті.
+
+## 1) Оголосіть свій вміст (спільно для React і Next.js)
+
+Створіть файл оголошення вмісту поруч із вашим компонентом. Це тримає переклади близько до місця їх використання і забезпечує type safety.
+
+```ts fileName="component.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+const componentContent = {
+  key: "component-example",
+  content: {
+    title: t({
+      uk: "Привіт",
+      en: "Hello",
+      fr: "Bonjour",
+      es: "Hola",
+    }),
+    description: t({
+      uk: "Багатомовний React-компонент",
+      en: "A multilingual React component",
+      fr: "Un composant React multilingue",
+      es: "Un componente React multilingüe",
+    }),
+  },
+} satisfies Dictionary;
+
+export default componentContent;
+```
+
+JSON також підтримується, якщо ви віддаєте перевагу конфігураційним файлам.
+
+```json fileName="component.content.json"
+{
+  "$schema": "https://intlayer.org/schema.json",
+  "key": "component-example",
+  "content": {
+    "title": {
+      "nodeType": "translation",
+      "translation": {
+        "uk": "Привіт",
+        "en": "Hello",
+        "fr": "Bonjour",
+        "es": "Hola"
+      }
+    },
+    "description": {
+      "nodeType": "translation",
+      "translation": {
+        "uk": "Багатомовний React-компонент",
+        "en": "A multilingual React component",
+        "fr": "Un composant React multilingue",
+        "es": "Un componente React multilingüe"
+      }
+    }
+  }
+}
+```
+
+## 2) Отримайте свій вміст
+
+### Випадок A — React-додаток (Vite/SPA)
+
+Стандартний підхід: використовуйте `useIntlayer` для отримання за ключем. Це тримає компоненти компактними та типізованими.
+
+```tsx fileName="ComponentExample.tsx"
+import { useIntlayer } from "react-intlayer";
+
+export function ComponentExample() {
+  const content = useIntlayer("component-example");
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </div>
+  );
+}
+```
+
+Для server-side рендерингу або за межами провайдера: використовуйте `react-intlayer/server` і передавайте явний параметр `locale`, коли це потрібно.
+
+```tsx fileName="ServerRenderedExample.tsx"
+import { useIntlayer } from "react-intlayer/server";
+
+export function ServerRenderedExample({ locale }: { locale: string }) {
+  const content = useIntlayer("component-example", locale);
+  return (
+    <>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </>
+  );
+}
+```
+
+Альтернатива: `useDictionary` може зчитувати всю оголошену структуру, якщо ви віддаєте перевагу розміщенню структури в місці виклику.
+
+```tsx fileName="ComponentWithDictionary.tsx"
+import { useDictionary } from "react-intlayer";
+import componentContent from "./component.content";
+
+export function ComponentWithDictionary() {
+  const { title, description } = useDictionary(componentContent);
+  return (
+    <div>
+      <h1>{title}</h1>
+      <p>{description}</p>
+    </div>
+  );
+}
+```
+
+### Варіант B — Next.js (App Router)
+
+Надавайте перевагу server components для безпеки даних та продуктивності. Використовуйте `useIntlayer` з `next-intlayer/server` у серверних файлах, а `useIntlayer` з `next-intlayer` — у client components.
+
+```tsx fileName="app/[locale]/example/ServerComponent.tsx"
+import { useIntlayer } from "next-intlayer/server";
+
+export default function ServerComponent() {
+  const content = useIntlayer("component-example");
+  return (
+    <>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </>
+  );
+}
+```
+
+```tsx fileName="app/[locale]/example/ClientComponent.tsx"
+"use client";
+
+import { useIntlayer } from "next-intlayer";
+
+export function ClientComponent() {
+  const content = useIntlayer("component-example");
+  return (
+    <div>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+    </div>
+  );
+}
+```
+
+Порада: Для метаданих сторінки та SEO ви також можете отримувати контент за допомогою `getIntlayer` та генерувати багатомовні URL-адреси за допомогою `getMultilingualUrls`.
+
+## Чому компонентний підхід Intlayer найкращий
+
+- **Колокація**: декларації контенту знаходяться поруч із компонентами, що зменшує розбіжності та покращує повторне використання в дизайн-системах.
+- **Типобезпека**: ключі та структури строго типізовані; відсутні переклади виявляються під час збірки, а не під час виконання.
+- **Server-first**: Працює нативно в серверних компонентах для кращої безпеки та продуктивності; client hooks залишаються ергономічними.
+- **Tree-shaking**: У бандл потрапляє лише контент, який використовує компонент, що допомагає зменшити розмір payload у великих додатках.
+- **DX & tooling**: Вбудований middleware, SEO-хелпери та необов'язкові Visual Editor/AI-переклади спрощують щодену роботу.
+
+Дивіться порівняння та шаблони в огляді, орієнтованому на Next.js: https://intlayer.org/blog/next-i18next-vs-next-intl-vs-intlayer
+
+## Пов'язані посібники та довідкові матеріали
+
+- Налаштування React (Vite): https://intlayer.org/doc/environment/vite-and-react
+- React Router v7: https://intlayer.org/doc/environment/vite-and-react/react-router-v7
+- TanStack Start: https://intlayer.org/doc/environment/vite-and-react/tanstack-start
+- Налаштування Next.js: https://intlayer.org/doc/environment/nextjs
+- Чому обрати Intlayer замість next-intl та next-i18next - https://intlayer.org/blog/next-i18next-vs-next-intl-vs-intlayer
+
+Ці сторінки містять end-to-end налаштування, провайдери, маршрутизацію та SEO-хелпери.