@intlayer/docs 7.5.10 → 7.5.12

package/docs/tr/plugins/sync-json.md

@@ -108,18 +108,22 @@ syncJSON({
   source: ({ key, locale }) => string, // zorunlu
   location?: string, // isteğe bağlı etiket, varsayılan: "plugin"
   priority?: number, // isteğe bağlı öncelik, çakışma çözümü için, varsayılan: 0
-  format?: 'intlayer' | 'icu' | 'i18next', // isteğe bağlı formatlayıcı, varsayılan: 'intlayer'
+  format?: 'intlayer' | 'icu' | 'i18next', // isteğe bağlı formatlayıcı, Intlayer runtime uyumluluğu için kullanılır
 });
 ```
 
 #### `format` ('intlayer' | 'icu' | 'i18next')
 
-JSON dosyalarını senkronize ederken sözlük içeriği için kullanılacak formatlayıcıyı belirtir. Bu, çeşitli i18n kütüphaneleriyle uyumlu farklı mesaj formatlama sözdizimlerini kullanmanıza olanak tanır.
+JSON dosyalarını senkronize ederken sözlük içeriği için kullanılacak formatlayıcıyı belirtir. Bu, Intlayer runtime ile uyumlu farklı mesaj formatlama sözdizimlerini kullanmanıza olanak tanır.
 
+- `undefined`: Hiçbir formatlayıcı kullanılmayacak, JSON içeriği olduğu gibi kullanılacak.
 - `'intlayer'`: Varsayılan Intlayer formatlayıcısı (varsayılan).
 - `'icu'`: ICU mesaj formatlamasını kullanır (react-intl, vue-i18n gibi kütüphanelerle uyumlu).
 - `'i18next'`: i18next mesaj formatlamasını kullanır (i18next, next-i18next, Solid-i18next ile uyumlu).
 
+> Bir formatlayıcı kullanmanın JSON içeriğinizi girdi ve çıktıda dönüştüreceğini unutmayın. ICU çoğulları gibi karmaşık JSON kuralları için, ayrıştırma girdi ve çıktı arasında 1'e 1 eşleme garanti edemeyebilir.
+> Intlayer runtime kullanmıyorsanız, bir formatlayıcı ayarlamamayı tercih edebilirsiniz.
+
 **Örnek:**
 
 ```ts

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-хелпери.