@intlayer/docs 7.5.11 → 7.5.13

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/CI_CD.md

@@ -0,0 +1,198 @@
+---
+createdAt: 2025-05-20
+updatedAt: 2025-08-13
+title: "Інтеграція CI/CD"
+description: "Дізнайтеся, як інтегрувати Intlayer у ваш CI/CD конвеєр для автоматизованого керування контентом та розгортання."
+keywords:
+  - CI/CD
+  - Безперервна інтеграція
+  - Безперервне розгортання
+  - Автоматизація
+  - Інтернаціоналізація
+  - Документація
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - ci-cd
+history:
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: Ініціалізація історії
+---
+
+# Автоматичне генерування перекладів у CI/CD конвеєрі
+
+Intlayer дозволяє автоматично створювати переклади для ваших файлів декларації контенту. Існує кілька способів досягти цього залежно від вашого робочого процесу.
+
+## Зміст
+
+<TOC/>
+
+## Використання CMS
+
+З Intlayer ви можете використовувати робочий процес, у якому локально оголошується лише одна локаль, тоді як усі переклади керуються віддалено через CMS. Це дозволяє повністю відокремити вміст і переклади від codebase, надаючи редакторам вмісту більше гнучкості та забезпечуючи Live Sync (немає потреби перебудовувати застосунок, щоб застосувати зміни).
+
+### Приклад конфігурації
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.SPANISH, Locales.FRENCH],
+    requiredLocales: [Locales.ENGLISH], // Optional locales will be managed remotely
+    defaultLocale: Locales.ENGLISH,
+  },
+  editor: {
+    // Облікові дані CMS, якщо ви використовуєте CMS
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+    liveSync: true,
+  },
+  ai: {
+    applicationContext: "This is a test application", // Допомагає забезпечити узгоджене генерування перекладів
+  },
+};
+
+export default config;
+```
+
+Щоб дізнатися більше про CMS, зверніться до [офіційної документації](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/intlayer_CMS.md).
+
+## Використання Husky
+
+Ви можете інтегрувати генерацію перекладів у ваш локальний Git-воркфлоу за допомогою [Husky](https://typicode.github.io/husky/).
+
+### Приклад конфігурації
+
+```ts fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.SPANISH, Locales.FRENCH],
+    requiredLocales: [Locales.ENGLISH], // Необов’язкові локалі обробляються віддалено
+    defaultLocale: Locales.ENGLISH,
+  },
+  editor: {
+    clientId: process.env.INTLAYER_CLIENT_ID,
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+  },
+  ai: {
+    provider: "openai",
+    apiKey: process.env.OPENAI_API_KEY, // Використайте власний API-ключ
+
+    applicationContext: "This is a test application", // Допомагає забезпечити узгоджене генерування перекладів
+  },
+};
+
+export default config;
+```
+
+```bash fileName=".husky/pre-push"
+npx intlayer build                          # Щоб переконатися, що словники оновлені
+npx intlayer fill --unpushed --mode fill    # Заповнює лише відсутній вміст, не оновлює існуючий
+```
+
+> For more information about Intlayer CLI commands and their usage, refer to the [CLI documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/cli/index.md).
+>
+> If you have multiple apps in your repo using separate intlayer instances, you can use the `--base-dir` argument like this:
+
+```bash fileName=".husky/pre-push"
+# Додаток 1
+npx intlayer build --base-dir ./app1
+npx intlayer fill --base-dir ./app1 --unpushed --mode fill
+
+# Додаток 2
+npx intlayer build --base-dir ./app2
+npx intlayer fill --base-dir ./app2 --unpushed --mode fill
+```
+
+## Використання GitHub Actions
+
+Intlayer надає CLI-команду для автоматичного заповнення та перегляду вмісту словників. Це можна інтегрувати у ваш робочий процес CI/CD за допомогою GitHub Actions.
+
+```yaml fileName=".github/workflows/intlayer-translate.yml"
+name: Intlayer Авто-заповнення
+# Умови запуску цього workflow
+on:
+  pull_request:
+    branches:
+      - "main"
+
+permissions:
+  contents: write
+  pull-requests: write
+
+concurrency:
+  group: "autofill-${{ github.ref }}"
+  cancel-in-progress: true
+
+jobs:
+  autofill:
+    runs-on: ubuntu-latest
+    env:
+      # Конфігурація OpenAI
+      AI_MODEL: openai
+      AI_PROVIDER: gpt-5-mini
+      AI_API_KEY: ${{ secrets.AI_API_KEY }}
+
+    steps:
+      # Крок 1: Отримати останній код з репозиторію
+      - name: ⬇️ Клонувати репозиторій
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: true # Зберегти облікові дані для створення PR
+          fetch-depth: 0 # Отримати повну історію git для аналізу diff
+
+      # Крок 2: Налаштування середовища Node.js
+      - name: 🟢 Налаштувати Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20 # Використовуйте Node.js 20 LTS для стабільності
+
+      # Крок 3: Встановити залежності проєкту
+      - name: 📦 Встановити залежності
+        run: npm install
+
+      # Крок 4: Встановити Intlayer CLI глобально для керування перекладами
+      - name: 📦 Встановити Intlayer
+        run: npm install -g intlayer-cli
+
+      # Крок 5: Побудувати проєкт Intlayer для генерації файлів перекладу
+      - name: ⚙️ Побудувати проєкт Intlayer
+        run: npx intlayer build
+
+      # Крок 6: Використати AI для автоматичного заповнення відсутніх перекладів
+      - name: 🤖 Автоматично заповнити відсутні переклади
+        run: npx intlayer fill --git-diff --mode fill --provider $AI_PROVIDER --model $AI_MODEL --api-key $AI_API_KEY
+
+      # Крок 7: Перевірити наявність змін і закомітити їх
+      - name: 🔍 Перевірити наявність змін
+        id: check-changes
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            echo "has-changes=true" >> $GITHUB_OUTPUT
+          else
+            echo "has-changes=false" >> $GITHUB_OUTPUT
+          fi
+
+      # Крок 8: Закомітити та відправити зміни, якщо вони є
+      - name: 📤 Закомітити та відправити зміни
+        if: steps.check-changes.outputs.has-changes == 'true'
+        run: |
+          git config --local user.email "action@github.com"
+          git config --local user.name "GitHub Action"
+          git add .
+          git commit -m "chore: автоматичне заповнення відсутніх перекладів [skip ci]"
+          git push origin HEAD:${{ github.head_ref }}
+```
+
+Щоб налаштувати змінні середовища, перейдіть у GitHub → Settings → Secrets and variables → Actions і додайте секрет .
+
+> Так само, як і для Husky, у випадку монорепозиторію ви можете використовувати аргумент `--base-dir`, щоб послідовно обробляти кожен додаток.
+
+> За замовчуванням аргумент `--git-diff` фільтрує словники, які містять зміни від бази (за замовчуванням `origin/main`) до поточної гілки (за замовчуванням: `HEAD`).
+
+> Для отримання додаткової інформації про команди Intlayer CLI та їх використання зверніться до [CLI documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/cli/index.md).

package/docs/uk/autoFill.md

@@ -0,0 +1,307 @@
+---
+createdAt: 2025-03-13
+updatedAt: 2025-09-20
+title: Автозаповнення
+description: Дізнайтеся, як використовувати функцію автозаповнення в Intlayer для автоматичного заповнення контенту на основі заздалегідь визначених шаблонів. Дотримуйтесь цієї документації, щоб ефективно реалізувати можливості автозаповнення у вашому проєкті.
+keywords:
+  - Автозаповнення
+  - Автоматизація контенту
+  - Динамічний контент
+  - Intlayer
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - concept
+  - auto-fill
+history:
+  - version: 7.0.0
+    date: 2025-10-23
+    changes: Перейменовано `autoFill` на `fill` та оновлено поведінку
+  - version: 6.0.0
+    date: 2025-09-20
+    changes: Додано глобальну конфігурацію
+  - version: 6.0.0
+    date: 2025-09-17
+    changes: Додано змінну `{{fileName}}`
+  - version: 5.5.10
+    date: 2025-06-29
+    changes: Ініціалізовано історію
+---
+
+# Заповнення файлів декларації контенту
+
+**Файли декларації контенту з автозаповненням** у вашому CI — це спосіб прискорити робочий процес розробки.
+
+## Розуміння поведінки
+
+Команда `fill` має два режими:
+
+- **Complete**: Автоматично заповнює весь відсутній контент для кожної локалі та редагує поточний файл або інший файл, якщо вказано. Тобто режим Complete пропускає переклад наявного контенту, якщо він уже перекладений.
+- **Review**: Автоматично заповнює **весь** контент для кожної локалі та генерує файл для поточного або вказаного іншого файлу.
+
+Команда `fill` обробляє лише ваші локальні файли декларації контенту. Тобто вона не обробляє віддалений контент із CMS — CMS має власну систему керування перекладами.
+Якщо ви використовуєте плагіни, такі як `@intlayer/sync-json-plugin`, Intlayer перетворить JSON-файли на файли декларацій локалізованого контенту. Тобто вони будуть оброблятися командою `fill`.
+
+У новостворених файлах міститься інструкція `filled` як метадані словника. Ця інструкція використовується Intlayer, щоб визначити, чи файл був автозаповнений, і, якщо так, пропустити цей файл при наступному перекладі.
+
+Intlayer також враховуватиме такі інструкції для автозаповнення:
+
+- Із вашого файлу `.content.{ts|js|json}` → інструкція `fill`
+- Із конфігураційного файлу `.intlayer.config.ts` → інструкція `dictionary.fill`
+- Якщо ніде не вказано — за замовчуванням буде встановлено `true`
+
+Для деклараційних файлів вмісту, що призначені для окремої локалі (per-locale), інструкція `true` буде замінена на `./{{fileName}}.fill.content.json`. Це відбувається тому, що такий per-locale деклараційний файл вмісту не може отримувати додатковий локалізований вміст. Отже, буде згенеровано новий файл, щоб не перезаписувати існуючий файл.
+
+## Поведінка за замовчуванням
+
+За замовчуванням глобальний параметр `fill` встановлено в `true`, що означає, що Intlayer автоматично заповнюватиме всі файли вмісту та редагуватиме сам файл. Цю поведінку можна налаштувати кількома способами:
+
+### Глобальні параметри конфігурації
+
+1. **`fill: true` (default)** - Автоматично заповнювати всі локалі та редагувати поточний файл
+2. **`fill: false`** - Вимкнути автоматичне заповнення для цього файлу вмісту
+3. **`fill: "./relative/path/to/file"`** - Створює/оновлює вказаний файл без редагування поточного, вказуючи на відносний шлях, який резольвується на основі розташування поточного файлу
+4. **`fill: "/absolute/path/to/file"`** - Створює/оновлює вказаний файл без редагування поточного, вказуючи шлях, що резольвується відносно базового каталогу (поле `baseDir` у файлі конфігурації `.intlayer.config.ts`)
+5. **`fill: "C:\\absolute\path\to\file"`** - Створює/оновлює вказаний файл без редагування поточного, вказуючи на абсолютний шлях, який резольвується на основі вашої операційної системи
+6. **`fill: { [key in Locales]?: string }`** - Створює/оновлює вказаний файл для кожної локалі
+
+### Зміни поведінки у v7
+
+У версії v7 поведінка команди `fill` була оновлена:
+
+- **`fill: true`** - Перезаписує поточний файл із заповненим вмістом для всіх локалей
+- **`fill: "path/to/file"`** - Заповнює вказаний файл, не змінюючи поточний файл
+- **`fill: false`** - Повністю відключає автоматичне заповнення
+
+При використанні опції шляху для запису в інший файл механізм fill працює через _master-slave_ зв'язок між файлами декларацій вмісту. Основний (master) файл є джерелом істини, і коли він оновлюється, Intlayer автоматично застосовує ці зміни до похідних (filled) файлів декларацій, вказаних у шляху.
+
+### Налаштування для кожної локалі
+
+Ви також можете налаштувати поведінку для кожної локалі, використовуючи об'єкт:
+
+```ts fileName="intlayer.config.ts"
+const config: IntlayerConfig = {
+  content: {
+    internationalization: {
+      locales: [Locales.ENGLISH, Locales.FRENCH, Locales.POLISH],
+      defaultLocale: Locales.ENGLISH,
+      requiredLocales: [Locales.ENGLISH], // Рекомендовано, щоб уникнути помилки Property 'pl' is missing in type '{ en: string; xxx } on your t function if
+    },
+  },
+  dictionary: {
+    fill: {
+      en: true, // Заповнює та редагує поточний файл для англійської
+      fr: "./translations/fr.json", // Створює окремий файл для французької
+      es: false, // Вимикає заповнення для іспанської
+    },
+  },
+};
+```
+
+Це дозволяє мати різну поведінку заповнення для різних локалей у межах одного проєкту.
+
+```ts fileName="src/components/example/example.content.ts"
+import { Locales, type Dictionary } from "intlayer";
+
+const exampleContent = {
+  key: "example",
+  locale: Locales.ENGLISH,
+  fill: "./example.content.json",
+  content: {
+    contentExample: "Це приклад вмісту",
+  },
+} satisfies Dictionary;
+
+export default exampleContent;
+```
+
+Ось [файл декларації вмісту на рівні локалі](https://github.com/aymericzip/intlayer/blob/main/docs/docs/uk/per_locale_file.md), який використовує інструкцію `fill`.
+
+Потім, коли ви виконаєте наступну команду:
+
+```bash
+npx intlayer fill --file 'src/components/example/example.content.ts'
+```
+
+Intlayer автоматично згенерує похідний файл декларації за адресою `src/components/example/example.content.json`, заповнивши всі локалі, які ще не оголошені в основному файлі.
+
+```json5 fileName="src/components/example/example.content.json"
+{
+  "key": "example",
+  "content": {
+    "contentExample": {
+      "nodeType": "translation",
+      "translation": {
+        "uk": "Це приклад вмісту",
+        "fr": "Ceci est un exemple de contenu",
+        "es": "Este es un ejemplo de contenido",
+      },
+    },
+  },
+}
+```
+
+Після цього обидва файли декларацій будуть об'єднані в один словник, доступний за допомогою стандартного хука `useIntlayer("example")` (React) / composable (Vue).
+
+## Глобальна конфігурація
+
+Ви можете налаштувати глобальну конфігурацію автоматичного заповнення у файлі `intlayer.config.ts`.
+
+```ts fileName="intlayer.config.ts"
+import { type IntlayerConfig, Locales } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
+    requiredLocales: [Locales.ENGLISH, Locales.FRENCH],
+  },
+  dictionary: {
+    // Автоматично згенерувати відсутні переклади для всіх словників
+    fill: "./{{fileName}}Filled.content.ts",
+    //
+    // fill: "/messages/{{locale}}/{{key}}/{{fileName}}.content.json",
+    //
+    // fill: true, // автоматично згенерувати відсутні переклади для всіх словників, як при використанні "./{{fileName}}.content.json"
+    //
+    // fill: {
+    //   en: "./{{fileName}}.en.content.json",
+    //   fr: "./{{fileName}}.fr.content.json",
+    //   es: "./{{fileName}}.es.content.json",
+    // },
+  },
+};
+
+export default config;
+```
+
+Ви все ще можете тонко налаштувати для кожного словника, використовуючи поле `fill` у файлах контенту. Intlayer спочатку врахує конфігурацію для конкретного словника, а потім відкотиться до глобальної конфігурації.
+
+## Формат автозаповнених файлів
+
+Рекомендований формат для автозаповнених файлів декларацій — **JSON**, оскільки це допомагає уникнути обмежень форматування. Однак Intlayer також підтримує `.ts`, `.js`, `.mjs`, `.cjs` та інші формати.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  fill: "./example.filled.content.ts",
+  content: {
+    // Ваш контент
+  },
+};
+```
+
+Це згенерує файл за шляхом:
+
+```
+src/components/example/example.filled.content.ts
+```
+
+> Генерація `.js`, `.ts` та схожих файлів працює таким чином:
+>
+> - Якщо файл вже існує, Intlayer розпарсить його, використовуючи AST (Abstract Syntax Tree), щоб знайти кожне поле та вставити будь-які відсутні переклади.
+> - Якщо файл не існує, Intlayer згенерує його, використовуючи шаблон файлу декларації контенту за замовчуванням.
+
+## Абсолютні шляхи
+
+Поле `fill` також підтримує абсолютні шляхи.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  fill: "/messages/example.content.json",
+  content: {
+    // Ваш контент
+  },
+};
+```
+
+Це згенерує файл за шляхом:
+
+```
+/messages/example.content.json
+```
+
+## Автогенерація файлів декларацій контенту для кожної локалі
+
+Поле `fill` також підтримує генерацію **файлів декларацій контенту для кожної локалі**.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  fill: {
+    fr: "./example.fr.content.json",
+    es: "./example.es.content.json",
+  },
+  content: {
+    // Ваш контент
+  },
+};
+```
+
+Це згенерує два окремі файли:
+
+- `src/components/example/example.fr.content.json`
+- `src/components/example/example.es.content.json`
+
+> У цьому випадку, якщо об'єкт не містить усіх локалей, Intlayer пропустить генерацію решти локалей.
+
+## Фільтрація автозаповнення для певної локалі
+
+Використання об'єкта у полі `fill` дозволяє застосовувати фільтри та генерувати лише файли для певних локалей.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  fill: {
+    fr: "./example.fr.content.json",
+  },
+  content: {
+    // Ваш контент
+  },
+};
+```
+
+Це згенерує лише файл перекладу французькою.
+
+## Змінні шляху
+
+Ви можете використовувати змінні всередині шляху `fill`, щоб динамічно формувати цільові шляхи для згенерованих файлів.
+
+**Доступні змінні:**
+
+- `{{locale}}` – код локалі (наприклад `fr`, `es`)
+- `{{fileName}}` – ім'я файлу (наприклад `index`)
+- `{{key}}` – ключ словника (наприклад `example`)
+
+```ts fileName="src/components/example/index.content.ts"
+const exampleContent = {
+  key: "example",
+  fill: "/messages/{{locale}}/{{key}}.content.json",
+  content: {
+    // Ваш вміст
+  },
+};
+```
+
+Це згенерує:
+
+- `/messages/fr/example.content.json`
+- `/messages/es/example.content.json`
+
+```ts fileName="src/components/example/index.content.ts"
+const exampleContent = {
+  key: "example",
+  fill: "./{{fileName}}.content.json",
+  content: {
+    // Ваш вміст
+  },
+};
+```
+
+Це згенерує:
+
+/// `./index.content.json`
+/// `./index.content.json`