@intlayer/docs 5.8.1 → 6.0.0-canary.0

package/docs/ru/testing.md

@@ -0,0 +1,202 @@
+---
+createdAt: 2025-03-01
+updatedAt: 2025-09-20
+title: Тестирование вашего контента
+description: Узнайте, как тестировать ваш контент с помощью Intlayer.
+keywords:
+  - Тестирование
+  - Intlayer
+  - Интернационализация
+  - CMS
+  - Система управления контентом
+  - Визуальный редактор
+slugs:
+  - doc
+  - testing
+---
+
+# Тестирование вашего контента
+
+Это руководство показывает, как автоматически проверять полноту ваших словарей, выявлять отсутствующие переводы до выпуска и тестировать локализованный пользовательский интерфейс в вашем приложении.
+
+---
+
+## Что вы можете тестировать
+
+- **Отсутствующие переводы**: провалить CI, если для любого словаря отсутствуют обязательные локали.
+- **Отрисовка локализованного UI**: рендерить компоненты с провайдером конкретной локали и проверять видимый текст/атрибуты.
+- **Аудиты во время сборки**: запускать быстрый аудит локально через CLI.
+
+---
+
+## Быстрый старт: аудит через CLI
+
+Запустите аудит из корня вашего проекта:
+
+```bash
+npx intlayer content test
+```
+
+Полезные флаги:
+
+- `--env-file [path]`: загрузить переменные окружения из файла.
+- `-e, --env [name]`: выбрать профиль окружения.
+- `--base-dir [path]`: задать базовую директорию приложения для разрешения путей.
+- `--verbose`: показывать подробные логи.
+- `--prefix [label]`: добавлять префикс к строкам логов.
+
+Примечание: CLI выводит подробный отчет, но не завершает работу с ошибкой при обнаружении проблем. Для контроля в CI добавьте юнит-тест (ниже), который проверяет отсутствие отсутствующих обязательных локалей.
+
+---
+
+## Программное тестирование (Vitest/Jest)
+
+Используйте API Intlayer CLI, чтобы проверить, что отсутствующих переводов для обязательных локалей нет.
+
+```ts file=i18n.test.ts
+/* @vitest-environment node */
+import { listMissingTranslations } from "intlayer/cli";
+import { describe, expect, it } from "vitest";
+
+describe("переводы", () => {
+  it("отсутствуют обязательные локали", () => {
+    const result = listMissingTranslations();
+
+    if (result.missingRequiredLocales.length > 0) {
+      // Полезно, когда тест не проходит локально или в CI
+      console.log(result.missingTranslations);
+    }
+
+    expect(result.missingRequiredLocales).toHaveLength(0);
+  });
+});
+```
+
+Эквивалент для Jest:
+
+```ts file=i18n.test.ts
+import { listMissingTranslations } from "intlayer/cli";
+
+test("отсутствуют обязательные локали", () => {
+  const result = listMissingTranslations();
+
+  if (result.missingRequiredLocales.length > 0) {
+    // eslint-disable-next-line no-console
+    console.log(result.missingTranslations);
+  }
+
+  expect(result.missingRequiredLocales).toHaveLength(0);
+});
+```
+
+Как это работает:
+
+- Intlayer читает вашу конфигурацию (locales, requiredLocales) и объявленные словари, затем сообщает:
+  - `missingTranslations`: для каждого ключа, какие локали отсутствуют и из какого файла.
+  - `missingLocales`: объединение всех отсутствующих локалей.
+  - `missingRequiredLocales`: подмножество, ограниченное `requiredLocales` (или все локали, если `requiredLocales` не установлены).
+
+---
+
+## Тестирование локализованного UI (React / Next.js)
+
+Рендерьте компоненты под провайдером Intlayer и проверяйте видимый контент.
+
+Пример для React (Testing Library):
+
+```tsx
+import { IntlayerProvider } from "react-intlayer/client";
+import { render, screen } from "@testing-library/react";
+import { MyComponent } from "./MyComponent";
+
+test("renders localized title in English", () => {
+  render(
+    <IntlayerProvider locale="en-US">
+      <MyComponent />
+    </IntlayerProvider>
+  );
+
+  expect(
+    screen.getByText("Ожидаемый английский заголовок")
+  ).toBeInTheDocument();
+});
+```
+
+Пример для Next.js (App Router): используйте обертку фреймворка:
+
+```tsx
+import { IntlayerClientProvider } from "next-intlayer/client";
+import { render, screen } from "@testing-library/react";
+import { MyPage } from "./MyPage";
+
+test("отображает локализованный заголовок на французском", () => {
+  render(
+    <IntlayerClientProvider locale="fr-FR">
+      <MyPage />
+    </IntlayerClientProvider>
+  );
+  expect(
+    screen.getByRole("heading", { name: "Titre attendu" })
+  ).toBeInTheDocument();
+});
+```
+
+Советы:
+
+- Когда вам нужны необработанные строковые значения для атрибутов (например, `aria-label`), обращайтесь к полю `.value`, возвращаемому `useIntlayer` в React.
+- Храните словари рядом с компонентами для упрощения модульного тестирования и очистки.
+
+---
+
+## Непрерывная интеграция
+
+Добавьте тест, который будет прерывать сборку, если отсутствуют необходимые переводы.
+
+`package.json`:
+
+```json
+{
+  "scripts": {
+    "test:i18n": "vitest run -c"
+  }
+}
+```
+
+Пример GitHub Actions:
+
+```yaml
+name: CI
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      - run: npm run test:i18n
+```
+
+Опционально: запустите аудит CLI для получения удобочитаемого отчёта вместе с тестами:
+
+```bash
+npx intlayer content test --verbose
+```
+
+---
+
+## Устранение неполадок
+
+- Убедитесь, что ваша конфигурация Intlayer определяет `locales` и (опционально) `requiredLocales`.
+- Если ваше приложение использует динамические или удалённые словари, запускайте тесты в среде, где эти словари доступны.
+- Для смешанных монорепозиториев используйте `--base-dir`, чтобы указать CLI правильный корень приложения.
+
+---
+
+## История документации
+
+| Версия | Дата       | Изменения             |
+| ------ | ---------- | --------------------- |
+| 6.0.0  | 2025-09-20 | Введение тестирования |

package/docs/tr/CI_CD.md

@@ -0,0 +1,198 @@
+---
+createdAt: 2025-09-07
+updatedAt: 2025-09-07
+title: CI/CD Entegrasyonu
+description: Otomatik içerik yönetimi ve dağıtım için Intlayer'ı CI/CD hattınıza nasıl entegre edeceğinizi öğrenin.
+keywords:
+  - CI/CD
+  - Sürekli Entegrasyon
+  - Sürekli Dağıtım
+  - Otomasyon
+  - Uluslararasılaştırma
+  - Dokümantasyon
+  - Intlayer
+slugs:
+  - doc
+  - concept
+  - ci-cd
+---
+
+# CI/CD Hattında Çevirileri Otomatik Oluştur
+
+Intlayer, içerik bildirim dosyalarınız için çevirilerin otomatik olarak oluşturulmasına izin verir. İş akışınıza bağlı olarak bunu başarmanın birden fazla yolu vardır.
+
+## CMS Kullanarak
+
+Intlayer ile, sadece tek bir yerel ayar yerel olarak bildirilirken, tüm çevirilerin CMS aracılığıyla uzaktan yönetildiği bir iş akışı benimseyebilirsiniz. Bu, içerik ve çevirileri kod tabanından tamamen ayırmaya izin verir, içerik editörleri için daha fazla esneklik sunar ve sıcak içerik yeniden yüklemesini etkinleştirir (değişiklikleri uygulamak için uygulamayı yeniden oluşturmaya gerek yoktur).
+
+### Örnek Konfigürasyon
+
+```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], // İsteğe bağlı yerel ayarlar uzaktan yönetilecek
+    defaultLocale: Locales.ENGLISH,
+  },
+  editor: {
+    dictionaryPriorityStrategy: "distant_first", // Uzak içerik öncelikli
+
+    applicationURL: process.env.APPLICATION_URL, // CMS tarafından kullanılan uygulama URL'si
+
+    clientId: process.env.INTLAYER_CLIENT_ID, // CMS kimlik bilgileri
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+  },
+  ai: {
+    applicationContext: "This is a test application", // Tutarlı çeviri oluşturmayı sağlar
+  },
+};
+
+export default config;
+```
+
+CMS hakkında daha fazla bilgi için [resmi dokümantasyona](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_CMS.md) bakın.
+
+## Husky Kullanarak
+
+[Husky](https://typicode.github.io/husky/) kullanarak çeviri oluşturmayı yerel Git iş akışınıza entegre edebilirsiniz.
+
+### Örnek Konfigürasyon
+
+```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], // İsteğe bağlı yerel ayarlar uzaktan yönetilir
+    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, // Kendi API anahtarınızı kullanın
+
+    applicationContext: "This is a test application", // Tutarlı çeviri oluşturmayı sağlar
+  },
+};
+
+export default config;
+```
+
+```bash fileName=".husky/pre-push"
+npx intlayer build                          # Sözlüklerin güncel olduğundan emin olun
+npx intlayer fill --unpushed --mode fill    # Sadece eksik içeriği doldurun, mevcut olanları güncellemez
+```
+
+> Intlayer CLI komutları ve kullanımları hakkında daha fazla bilgi için [CLI dokümantasyonuna](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_cli.md) bakın.
+
+> Deponuzda ayrı intlayer örnekleri kullanan birden fazla uygulama varsa, `--base-dir` argümanını şu şekilde kullanabilirsiniz:
+
+```bash fileName=".husky/pre-push"
+# Uygulama 1
+npx intlayer build --base-dir ./app1
+npx intlayer fill --base-dir ./app1 --unpushed --mode fill
+
+# Uygulama 2
+npx intlayer build --base-dir ./app2
+npx intlayer fill --base-dir ./app2 --unpushed --mode fill
+```
+
+## GitHub Actions Kullanarak
+
+Intlayer, sözlük içeriğini otomatik doldurmak ve gözden geçirmek için bir CLI komutu sağlar. Bu, GitHub Actions kullanarak CI/CD iş akışınıza entegre edilebilir.
+
+```yaml fileName=".github/workflows/intlayer-translate.yml"
+name: Intlayer Auto-Fill
+# Bu iş akışı için tetikleme koşulları
+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:
+      # Adım 1: Depodan en son kodu alın
+      - name: ⬇️ Depoyu kontrol et
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: true # PR oluşturmak için kimlik bilgilerini saklayın
+          fetch-depth: 0 # Fark analizi için tam git geçmişini alın
+
+      # Adım 2: Node.js ortamını ayarlayın
+      - name: 🟢 Node.js'i ayarla
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20 # Kararlılık için Node.js 20 LTS kullanın
+
+      # Adım 3: Proje bağımlılıklarını yükleyin
+      - name: 📦 Bağımlılıkları yükle
+        run: npm install
+
+      # Adım 4: Çeviri yönetimi için Intlayer CLI'yi global olarak yükleyin
+      - name: 📦 Intlayer'ı yükle
+        run: npm install -g intlayer-cli
+
+      # Adım 5: Çeviri dosyalarını oluşturmak için Intlayer projesini oluşturun
+      - name: ⚙️ Intlayer projesini oluştur
+        run: npx intlayer build
+
+      # Adım 6: Eksik çevirileri otomatik olarak doldurmak için AI kullanın
+      - name: 🤖 Eksik çevirileri otomatik doldur
+        run: npx intlayer fill --git-diff --mode fill --provider $AI_PROVIDER --model $AI_MODEL --api-key $AI_API_KEY
+
+      # Adım 7: Değişiklik olup olmadığını kontrol edin ve bunları commit edin
+      - name: � Değişiklikleri kontrol et
+        id: check-changes
+        run: |
+          if [ -n "$(git status --porcelain)" ]; then
+            echo "has-changes=true" >> $GITHUB_OUTPUT
+          else
+            echo "has-changes=false" >> $GITHUB_OUTPUT
+          fi
+
+      # Adım 8: Varsa değişiklikleri commit edin ve pushlayın
+      - name: 📤 Değişiklikleri commit et ve pushla
+        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: auto-fill missing translations [skip ci]"
+          git push origin HEAD:${{ github.head_ref }}
+```
+
+Ortam değişkenlerini ayarlamak için GitHub → Settings → Secrets and variables → Actions'a gidin ve sırrı ekleyin.
+
+> Husky ile aynı şekilde, monorepo durumunda her uygulamayı sırayla işlemek için `--base-dir` argümanını kullanabilirsiniz.
+
+> Varsayılan olarak, `--git-diff` argümanı base'den (varsayılan `origin/main`) mevcut branch'e (varsayılan: `HEAD`) kadar olan değişiklikleri içeren sözlükleri filtreler.
+
+> Intlayer CLI komutları ve kullanımları hakkında daha fazla bilgi için [CLI dokümantasyonuna](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/intlayer_cli.md) bakın.
+
+## Doküman Geçmişi
+
+| Sürüm  | Tarih      | Değişiklikler     |
+| ------ | ---------- | ----------------- |
+| 5.5.10 | 2025-06-29 | Geçmiş başlatıldı |

package/docs/tr/autoFill.md

@@ -0,0 +1,201 @@
+---
+createdAt: 2025-03-13
+updatedAt: 2025-09-20
+title: Otomatik Doldurma
+description: Intlayer'da önceden tanımlanmış kalıplara göre içeriği otomatik doldurmak için otomatik doldurma işlevinin nasıl kullanılacağını öğrenin. Projenizde otomatik doldurma özelliklerini verimli bir şekilde uygulamak için bu dokümantasyonu takip edin.
+keywords:
+  - Otomatik Doldurma
+  - İçerik Otomasyonu
+  - Dinamik İçerik
+  - Intlayer
+  - Next.js
+  - JavaScript
+  - React
+slugs:
+  - doc
+  - concept
+  - auto-fill
+---
+
+# Otomatik Doldurma İçerik Beyan Dosyası Çevirileri
+
+**Otomatik doldurma içerik beyan dosyaları**, geliştirme iş akışınızı hızlandırmanın bir yoludur.
+
+Otomatik doldurma mekanizması, içerik beyan dosyaları arasında bir _ana-uydu_ ilişkisi üzerinden çalışır. Ana (master) dosya güncellendiğinde, Intlayer bu değişiklikleri türetilmiş (otomatik doldurulmuş) beyan dosyalarına otomatik olarak uygular.
+
+```ts fileName="src/components/example/example.content.ts"
+import { Locales, type Dictionary } from "intlayer";
+
+const exampleContent = {
+  key: "example",
+  locale: Locales.ENGLISH,
+  autoFill: "./example.content.json",
+  content: {
+    contentExample: "Bu bir içerik örneğidir",
+  },
+} satisfies Dictionary;
+
+export default exampleContent;
+```
+
+İşte `autoFill` talimatını kullanan bir [her dil için içerik beyan dosyası](https://github.com/aymericzip/intlayer/blob/main/docs/docs/tr/per_locale_file.md).
+
+Sonra, aşağıdaki komutu çalıştırdığınızda:
+
+```bash
+npx intlayer fill --file 'src/components/example/example.content.ts'
+```
+
+Intlayer, ana dosyada henüz beyan edilmemiş tüm yerelleri doldurarak, türetilmiş beyan dosyasını `src/components/example/example.content.json` konumunda otomatik olarak oluşturacaktır.
+
+```json5 fileName="src/components/example/example.content.json"
+{
+  "key": "example",
+  "content": {
+    "contentExample": {
+      "nodeType": "translation",
+      "translation": {
+        "fr": "Ceci est un exemple de contenu",
+        "es": "Este es un ejemplo de contenido",
+      },
+    },
+  },
+}
+```
+
+Daha sonra, her iki beyan dosyası tek bir sözlükte birleştirilecek ve standart `useIntlayer("example")` hook'u (react) / composable'ı (vue) kullanılarak erişilebilir olacaktır.
+
+## Otomatik Doldurulmuş Dosya Formatı
+
+Önerilen otomatik doldurulmuş beyan dosyalarının formatı, biçimlendirme kısıtlamalarından kaçınmaya yardımcı olan **JSON** formatıdır. Ancak, Intlayer `.ts`, `.js`, `.mjs`, `.cjs` ve diğer formatları da destekler.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: "./example.filled.content.ts",
+  content: {
+    // İçeriğiniz
+  },
+};
+```
+
+Bu, şu dosyayı oluşturacaktır:
+
+```
+src/components/example/example.filled.content.ts
+```
+
+> `.js`, `.ts` ve benzeri dosyaların oluşturulması şu şekilde çalışır:
+>
+> - Dosya zaten mevcutsa, Intlayer her alanı bulmak ve eksik çevirileri eklemek için AST (Soyut Sözdizimi Ağacı) kullanarak dosyayı ayrıştırır.
+> - Dosya mevcut değilse, Intlayer varsayılan içerik beyan dosyası şablonunu kullanarak dosyayı oluşturur.
+
+## Mutlak Yollar
+
+`autoFill` alanı mutlak yolları da destekler.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: "/messages/example.content.json",
+  content: {
+    // İçeriğiniz
+  },
+};
+```
+
+Bu, şu dosyayı oluşturacaktır:
+
+```
+/messages/example.content.json
+```
+
+## Yerel Bazlı İçerik Beyan Dosyalarının Otomatik Oluşturulması
+
+`autoFill` alanı ayrıca **yerel bazlı** içerik beyan dosyalarının oluşturulmasını da destekler.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: {
+    fr: "./example.fr.content.json",
+    es: "./example.es.content.json",
+  },
+  content: {
+    // İçeriğiniz
+  },
+};
+```
+
+Bu, iki ayrı dosya oluşturacaktır:
+
+- `src/components/example/example.fr.content.json`
+- `src/components/example/example.es.content.json`
+
+> Bu durumda, nesne tüm yerelleri içermiyorsa, Intlayer kalan yerellerin oluşturulmasını atlar.
+
+## Belirli Yerel Otodoldurmayı Filtreleme
+
+`autoFill` alanı için bir nesne kullanmak, filtre uygulamanıza ve yalnızca belirli yerel dosyalarını oluşturmanıza olanak tanır.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: {
+    fr: "./example.fr.content.json",
+  },
+  content: {
+    // İçeriğiniz
+  },
+};
+```
+
+Bu sadece Fransızca çeviri dosyasını oluşturacaktır.
+
+## Yol Değişkenleri
+
+ `autoFill` yolu içinde değişkenler kullanarak oluşturulan dosyaların hedef yollarını dinamik olarak çözebilirsiniz.
+
+**Kullanılabilir değişkenler:**
+
+- `{{locale}}` – Yerel kodu (örneğin `fr`, `es`)
+- `{{fileName}}` – Dosya adı (örneğin `index`)
+- `{{key}}` – Sözlük anahtarı (örneğin `example`)
+
+```ts fileName="src/components/example/index.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: "/messages/{{locale}}/{{key}}.content.json",
+  content: {
+    // İçeriğiniz
+  },
+};
+```
+
+Bu, aşağıdaki dosyaları oluşturacaktır:
+
+- `/messages/fr/example.content.json`
+- `/messages/es/example.content.json`
+
+```ts fileName="src/components/example/index.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: "./{{fileName}}.content.json",
+  content: {
+    // İçeriğiniz
+  },
+};
+```
+
+Bu, aşağıdaki dosyaları oluşturacaktır:
+
+- `./index.content.json`
+- `./index.content.json`
+
+## Doküman Geçmişi
+
+| Sürüm   | Tarih      | Değişiklikler               |
+| ------- | ---------- | --------------------------- |
+| 6.0.0   | 2025-09-20 | Küresel yapılandırma eklendi |
+| 6.0.0   | 2025-09-17 | `{{fileName}}` değişkeni eklendi |
+| 5.5.10  | 2025-06-29 | Geçmiş başlatıldı           |