@intlayer/docs 8.12.5-canary.0 → 9.0.0-canary.2

package/docs/de/migration_from_next-i18next_to_intlayer.md

@@ -19,7 +19,7 @@ slugs:
   - migration
   - next-i18next
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-05
     changes: "Init history"
 author: aymericzip

package/docs/de/migration_from_next-intl_to_intlayer.md

@@ -17,7 +17,7 @@ slugs:
   - migration
   - next-intl
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-05
     changes: "Init history"
 author: aymericzip

package/docs/de/migration_from_nuxtjs_i18n_to_intlayer.md

@@ -18,7 +18,7 @@ slugs:
   - migration
   - nuxtjs-i18n
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-05
     changes: "Init history"
 author: aymericzip

package/docs/de/migration_from_react-i18next_to_intlayer.md

@@ -18,7 +18,7 @@ slugs:
   - migration
   - react-i18next
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-05
     changes: "Init history"
 author: aymericzip

package/docs/de/migration_from_vue-i18n_to_intlayer.md

@@ -17,7 +17,7 @@ slugs:
   - migration
   - vue-i18n
 history:
-  - version: 8.13.0
+  - version: 9.0.0
     date: 2026-06-05
     changes: "Init history"
 author: aymericzip

package/docs/de/releases/v8.md

@@ -1,6 +1,6 @@
 ---
 createdAt: 2025-09-22
-updatedAt: 2026-01-26
+updatedAt: 2026-06-14
 title: Neues Intlayer v8 - Was ist neu?
 description: Entdecken Sie die Neuerungen in Intlayer v8. Bedeutende Verbesserungen in der Developer Experience, der Inhaltsvalidierung und der Verwaltung von Dictionaries.
 keywords:
@@ -409,6 +409,16 @@ Weitere Einzelheiten finden Sie in der [Dokumentation zu HTML-Inhalten](https://
 
 ---
 
+## YAML- & Markdown-Inhaltsdateien (v8.10.0)
+
+Sie können Inhalte jetzt direkt mit den Dateierweiterungen `.content.md` und `.content.yaml` deklarieren. Dies ist perfekt für Langform-Inhalte, Blogs, Dokumentationen und Datenschutzrichtlinien.
+
+Diese Dateien sind vollständig über den Visual Editor bearbeitbar und bieten einen optimierten Workflow für nicht-technische Teammitglieder.
+
+Weitere Details finden Sie in der [Dokumentation zu YAML-Inhaltsdateien](https://intlayer.org/doc/concept/content#yaml-content-file) und der [Dokumentation zu Markdown-Inhaltsdateien](https://intlayer.org/doc/concept/content/markdown).
+
+---
+
 ## Benutzerdefinierte URL-Umschreibungen (Rewrites)
 
 Intlayer v8 führt Unterstützung für **benutzerdefinierte URL-Umschreibungen** ein, mit denen Sie locale-spezifische Pfade definieren können, die von der Standardstruktur `/locale/path` abweichen. Dies ist eine leistungsstarke Funktion zur Verbesserung der lokalen SEO und bietet eine natürlichere Benutzererfahrung für nicht-englischsprachige Nutzer.
@@ -753,6 +763,68 @@ export default {
   </Tab>
 </Tabs>
 
+## Unicode CLDR Pluralregeln (v8.8.0)
+
+Ein neuer `plural` Node-Helper wurde basierend auf den Pluralregeln des Unicode CLDR Projekts eingeführt, um die Unterstützung für komplexe Sprachen zu verbessern.
+
+```typescript fileName="src/openings.content.ts"
+import { plural, t, type Dictionary } from "intlayer";
+
+const openingsContent = {
+  key: "total_openings",
+  content: {
+    totalOpenings: t({
+      en: plural({
+        one: "{{count}} opening",
+        other: "{{count}} openings",
+      }),
+      fr: plural({
+        one: "{{count}} offre",
+        other: "{{count}} offres",
+      }),
+      de: plural({
+        // Added German translation for plural example
+        one: "{{count}} offene Stelle",
+        other: "{{count}} offene Stellen",
+      }),
+    }),
+  },
+} satisfies Dictionary;
+
+export default openingsContent;
+```
+
+Sie können den Zähler dann dynamisch in Ihrer Framework-Komponente übergeben:
+
+```tsx
+import type { FC } from "react";
+import { useIntlayer } from "react-intlayer";
+
+const OpeningsComponent: FC<{ count: number }> = ({ count }) => {
+  const { totalOpenings } = useIntlayer("total_openings");
+
+  return (
+    <div>
+      {/* In English:                                  */}
+      {/*  count=0  → "0 openings"   (other)           */}
+      {/*  count=1  → "1 opening"    (one)             */}
+      {/*  count=2  → "2 openings"   (other)           */}
+      {/*  count=21 → "21 openings"  (other)           */}
+      {/* In German:                                   */}
+      {/*  count=0  → "0 offene Stellen" (other)       */}
+      {/*  count=1  → "1 offene Stelle"  (one)         */}
+      {/*  count=2  → "2 offene Stellen" (other)       */}
+      {/*  count=21 → "21 offene Stellen" (other)      */}
+      <p>{totalOpenings(count)}</p>
+    </div>
+  );
+};
+```
+
+Weitere Informationen finden Sie in der [Dokumentation zur Pluralisierung](https://intlayer.org/doc/concept/content/plural).
+
+---
+
 ## Inhalts-Schema-Validierung
 
 Intlayer v8 führt die Schema-Validierung für Dictionaries ein. Sie können jetzt wiederverwendbare Validierungsschemata in Ihrer Konfiguration mit Zod definieren und auf Ihre Inhaltsdateien anwenden. Dies stellt sicher, dass Ihr Inhalt immer der erwarteten Struktur entspricht, und fängt Fehler bereits zur Build-Zeit ab.
@@ -798,6 +870,34 @@ Wenn der Inhalt nicht mit dem Schema übereinstimmt (z. B. der Titel zu kurz ist
 
 ---
 
+## TypeScript: IntlayerNode Primitive Accessors
+
+Der `IntlayerNode`-Typ wurde aktualisiert, um das direkte Aufrufen primitiver JavaScript-Methoden auf Inhaltsknoten zu ermöglichen. Dies macht es möglich, mit Ihren lokalisierten Inhalten direkt zu interagieren, als wären sie ein Standard-String-, Zahlen-, Boolean- oder Array-Primitiv.
+
+Unterstützt in React, Preact, Solid, Svelte, Vue und Angular.
+
+### String-Beispiel
+
+```typescript
+content.placeholder; // Gibt IntlayerNode<string> zurück
+content.placeholder.value; // Gibt string zurück
+content.placeholder.toString(); // Gibt string zurück
+content.placeholder.toLowerCase(); // Gibt string zurück
+String(content.placeholder); // Gibt string zurück
+content.placeholder.toUpperCase(); // Gibt großgeschriebenen string zurück
+content.placeholder.replace("a", "b"); // Gibt modifizierten string zurück
+```
+
+### Array-Beispiel
+
+```typescript
+content.myArrayOfString             // Gibt IntlayerNode<Array<string>> zurück
+content.myArrayOfString.find(...)   // Gibt Element zurück
+content.myArrayOfString.join(', ')  // Gibt verbundenen string zurück
+```
+
+---
+
 ### Verbesserte automatische Inhaltserkennung
 
 In v8 erkennt Intlayer intelligent Markdown-Syntax, HTML-Tags und Variablen-Insertions in Ihren Inhaltsstrings. Das bedeutet, dass Sie häufig auf Hilfsfunktionen wie `md()`, `html()` oder `insert()` verzichten können.
@@ -1003,6 +1103,17 @@ Die Intlayer VSCode-Extension erhält in v8 bedeutende Updates, um Ihren Interna
 
 ---
 
+## Tooling: C++ Watcher & OXC-basierter LSP (v8.12.0)
+
+Intlayer v8.12.0 bringt wesentliche Verbesserungen für die Developer Experience:
+
+- **Parcel Watcher**: Der Content Watcher wurde von `chokidar` zu `@parcel/watcher` migriert, wodurch natives C++ File Watching genutzt wird, um schnellere Updates und einen deutlich geringeren Speicherverbrauch zu ermöglichen.
+- **Neues Language Server Protocol (LSP)**: Ein brandneues LSP ist jetzt verfügbar. Basierend auf OXC-Parsing hilft es Ihrer IDE und Ihren AI-Agenten, `useIntlayer('my-key')`-Aufrufe nahtlos mit den entsprechenden `.content`-Dateien zu verknüpfen und umgekehrt.
+
+Weitere Details finden Sie in der [LSP-Dokumentation](https://intlayer.org/doc/lsp).
+
+---
+
 ## Compiler-Optimierungen
 
 Intlayer v8 enthält eine neue Caching-Schicht für den Markdown- und HTML-Compiler. Dies stellt sicher, dass identische Inhaltsstrings mit derselben Konfiguration nur einmal geparst werden, was den Overhead bei Re-Renderings oder bei der Verwendung desselben Inhalts an mehreren Stellen erheblich reduziert.
@@ -1058,6 +1169,48 @@ Intlayer v8 enthält eine neue Caching-Schicht für den Markdown- und HTML-Compi
 
 ---
 
+## Experimentelle Build-Optimierungen: Minify & Purge (v8.7.0)
+
+Intlayer v8.7.0 führt neue experimentelle Build-Funktionen in Ihrer `intlayer.config.ts` ein, die darauf abzielen, Ihr Produktions-Bundle zu optimieren:
+
+- **Dictionary Minification**: Minifiziert Dictionary-Dateien, um die Größe zu reduzieren.
+- **Unused Key Purging**: Scannt und entfernt ungenutzte Übersetzungsschlüssel aus Dictionaries und benennt aktive Schlüssel in kurze Zeichen um (z. B. `"products" -> "a"`, `"pricing" -> "b"`). Dies reduziert die Bundle-Größe um bis zu 5%.
+- **Disable TypeScript Checks**: Beschleunigt Builds, indem die TypeScript-Typüberprüfung während des Kompilierungsschritts deaktiviert wird.
+
+```typescript fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH],
+    defaultLocale: Locales.ENGLISH,
+  },
+  dictionary: {
+    importMode: "dynamic",
+  },
+  build: {
+    /**
+     * Minifiziert die Dictionaries, um die Bundle-Größe zu reduzieren.
+     */
+    minify: true,
+
+    /**
+     * Entfernt ungenutzte Schlüssel in Dictionaries.
+     */
+    purge: true,
+
+    /**
+     * Gibt an, ob der Build TypeScript-Typen überprüfen soll.
+     */
+    checkTypes: false,
+  },
+};
+
+export default config;
+```
+
+---
+
 ## Flexibilität: Einheitlicher Import-Modus
 
 Die boolesche Eigenschaft `live` wurde zugunsten der umfassenderen Eigenschaft `importMode` als veraltet markiert. Dies ermöglicht eine explizite Definition, wie Dictionaries geladen werden sollen: statisch, dynamisch oder via Live-Synchronisierung.
@@ -1205,6 +1358,49 @@ Markdown- und HTML-Inhalte in Svelte werden nun automatisch in HTML geparst, wen
 
 ---
 
+## Angular-Unterstützung: Vite Bundler (v8.11.0)
+
+Für Angular-Benutzer unterstützt Intlayer jetzt nativ den Vite Bundler durch ein neues benutzerdefiniertes esbuild-Plugin, was die Entwicklungs- und Build-Zeiten beschleunigt.
+
+Details zur Konfiguration finden Sie in der [Angular Environment Dokumentation](https://intlayer.org/doc/environment/angular).
+
+---
+
+## Sitemap-Generierung (v8.6.0)
+
+Intlayer generiert jetzt automatisch Sitemaps basierend auf Ihren Locales und dem Routing-Modus. Dies ist besonders nützlich für die SEO-Optimierung in Router-Architekturen wie TanStack Router:
+
+```typescript fileName="src/routes/sitemap.xml.ts"
+import { createFileRoute } from "@tanstack/react-router";
+import { generateSitemap } from "intlayer";
+
+const SITE_URL = (
+  import.meta.env.VITE_SITE_URL ?? "http://localhost:3000"
+).replace(/\/$/, "");
+
+export const Route = createFileRoute("/sitemap.xml")({
+  server: {
+    handlers: {
+      GET: async () => {
+        const sitemap = generateSitemap(
+          [
+            { path: "/", changefreq: "daily", priority: 1.0 },
+            { path: "/about", changefreq: "monthly", priority: 0.8 },
+          ],
+          { siteUrl: SITE_URL }
+        );
+
+        return new Response(sitemap, {
+          headers: { "Content-Type": "application/xml" },
+        });
+      },
+    },
+  },
+});
+```
+
+---
+
 ## Migrationshinweise von v7
 
 ### Konfigurationsänderungen

package/docs/de/releases/v9.md

@@ -0,0 +1,232 @@
+---
+createdAt: 2026-06-14
+updatedAt: 2026-06-14
+title: Neues Intlayer v9 – Was ist neu?
+description: Entdecken Sie die Neuerungen in Intlayer v9. Einführung von Drop-in-Kompatibilitätspaketen für beliebte i18n-Bibliotheken und Unterstützung für Collections, Variants und Dynamic Records.
+keywords:
+  - Intlayer
+  - Compatibility
+  - Migration
+  - Collections
+  - Variants
+  - Dynamic Records
+  - i18next
+  - next-intl
+  - vue-i18n
+slugs:
+  - doc
+  - releases
+  - v9
+author: aymericzip
+---
+
+# Neues Intlayer v9 – Was ist neu?
+
+Willkommen bei Intlayer v9! Dieses Major Release markiert einen riesigen Meilenstein bei der Vereinfachung des Migrationspfads zu Intlayer mit **Compat Adapter Packages** für wichtige i18n-Bibliotheken (`react-i18next`, `next-intl`, `vue-i18n`, etc.) und fügt Unterstützung für reichhaltige Inhaltsstrukturen hinzu: **Collections**, **Variants** und **Dynamic Records**.
+
+## Inhaltsverzeichnis
+
+<TOC levels={[2]} maxDepth={1} />
+
+---
+
+## Compat Adapter Packages
+
+Die Migration von beliebten i18n-Bibliotheken zu Intlayer ist jetzt einfacher denn je. Wir haben fünf Kompatibilitätspakete erstellt, die die **exakt gleichen öffentlichen APIs** wie Standard-i18n-Bibliotheken bereitstellen, aber die gesamte Übersetzungsarbeit zur Laufzeit an Intlayer delegieren.
+
+### Gleiche öffentliche API mit strenger Typisierung
+
+Durch das Ersetzen von Imports erhalten Sie alle Vorteile von Intlayer (einschließlich Compile-Time-Typsicherheit gegenüber Ihren tatsächlichen Dictionaries) mit minimalen Codeänderungen:
+
+- `@intlayer/i18next`
+- `@intlayer/react-i18next`
+- `@intlayer/next-intl`
+- `@intlayer/next-i18next`
+- `@intlayer/vue-i18n`
+
+Ändern Sie zum Beispiel einfach:
+
+```ts
+import { useTranslation } from "react-i18next";
+```
+
+zu:
+
+```ts
+import { useTranslation } from "@intlayer/react-i18next";
+```
+
+Ihre Keys werden nun **streng typisiert** gegenüber Ihren Intlayer-Dictionaries, was eine vollständige Dot-Path-Auto-Vervollständigung in Ihrer IDE bietet!
+
+### Bundler Alias Plugins (Vite, Next.js, Turbopack)
+
+Um die Migration ohne manuelles Umschreiben aller Import-Statements zu ermöglichen, enthält jedes Compat Adapter Package ein **benutzerdefiniertes Bundler-Plugin** (Vite oder Next.js) unter dem Subpfad `/plugin`.
+
+Diese Plugins schreiben bestehende Imports (z.B. `react-i18next` oder `next-intl`) zur Build-Zeit automatisch in ihre `@intlayer/*`-Äquivalente um.
+
+#### Next.js (Webpack / Turbopack) Beispiel
+
+Anstelle von `withIntlayer` umschließen Sie Ihre Next.js-Konfiguration mit dem Kompatibilitäts-Plugin:
+
+```ts fileName="next.config.ts"
+import { createNextI18nPlugin } from "@intlayer/next-i18next/plugin";
+import type { NextConfig } from "next";
+
+const withIntlayer = createNextI18nPlugin();
+const nextConfig: NextConfig = {};
+
+export default withIntlayer(nextConfig);
+```
+
+#### Vite (React, Vue, Solid, Svelte) Beispiel
+
+```ts fileName="vite.config.ts"
+import vueI18nVitePlugin from "@intlayer/vue-i18n/plugin";
+
+export default defineConfig({
+  plugins: [vueI18nVitePlugin()],
+});
+```
+
+---
+
+## Mutualized Runtime Resolver
+
+Alle Kompatibilitätsadapter leiten die Übersetzungsauflösung nun über einen einzigen, hochoptimierten Runtime-Parser: `@intlayer/core/messageFormat`.
+
+- **Interpolate Message**: Löst Standard `{{var}}` (Leerzeichen & Dot-Pfade), ICU-formatierte Argumente (`{v, number, percent}` etc.) und einfache `{var}`-Templates auf.
+- **Message Node Resolver**: Löst verschachtelte Nodes auf: `insert()`, `plural()` (CLDR-Pluralregeln), `enu()` (Aufzählung), `gender()`, HTML-Tags, Arrays und aufrufbare Funktions-Nodes.
+- **Tokenized Tag Parser**: Unterstützt Inline-XML/HTML-Tags und nummerierte Tags (z.B. `<1>children</1>`), um Rich-Text-Rendering out-of-the-box zu ermöglichen.
+
+---
+
+## Feature Spec: Collections, Variants & Dynamic Records
+
+Intlayer v9 geht über statische Schlüssel-Wert-Objekte hinaus und ermöglicht es Dictionaries, dynamische Layout-Strukturen zu deklarieren, die End-to-End vollständig typisiert sind.
+
+### 1. Collections
+
+Definieren Sie eine CMS-verwaltete Liste geordneter Elemente (z.B. FAQs, Produkte oder Bloglisten):
+
+```ts fileName="faq.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "faq",
+  content: [
+    {
+      question: t({
+        de: "Was ist Intlayer?",
+        en: "What is Intlayer?",
+        fr: "Qu'est-ce qu'Intlayer ?",
+      }),
+      answer: t({
+        de: "Ein i18n-Toolkit.",
+        en: "An i18n toolkit.",
+        fr: "Une boîte à outils i18n.",
+      }),
+    },
+  ],
+} satisfies Dictionary;
+```
+
+#### Verwendung:
+
+```ts
+// Alle Elemente abrufen
+const allFaqs = useIntlayer("faq"); // -> { question: string, answer: string }[]
+
+// Einzelnes Element nach Index abrufen
+const faq = useIntlayer("faq", { item: 1 }); // -> { question: string, answer: string }
+```
+
+### 2. Variants
+
+Liefern Sie A/B-Tests, saisonale Header, Feature Flags oder benutzerdefinierte Landing Pages:
+
+```ts fileName="hero.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "hero-banner",
+  variant: "default",
+  content: {
+    control: t({ de: "Willkommen", en: "Welcome", fr: "Bienvenue" }),
+    black_friday: t({
+      de: "Jetzt einkaufen",
+      en: "Shop now",
+      fr: "Acheter maintenant",
+    }),
+  },
+} satisfies Dictionary;
+```
+
+#### Verwendung:
+
+```ts
+const banner = useIntlayer("hero-banner", { variant: "black_friday" });
+```
+
+### 3. Dynamic Records
+
+Definieren Sie Dictionaries, deren Einträge zur Laufzeit dynamisch über Query-IDs geladen werden:
+
+```ts fileName="product.content.ts"
+import { t, type Dictionary } from "intlayer";
+
+export default {
+  key: "product-copy",
+  meta: {
+    id: "prod_123",
+    category: "books",
+  },
+  content: {
+    title: t({ de: "Clean Code", en: "Clean Code", fr: "Code Propre" }),
+  },
+} satisfies Dictionary;
+```
+
+#### Verwendung:
+
+```ts
+// Ruft nur das angeforderte Element dynamisch ab (erfordert Suspense)
+const product = useIntlayer("product-copy", {
+  id: "prod_123",
+  category: "books",
+});
+```
+
+---
+
+## Dynamisches Laden & Optimierungen der Bundle-Größe
+
+Um Bundles extrem klein zu halten, unterstützt Intlayer v9 dynamisches Lazy Loading.
+
+Stellen Sie in Ihrer Konfiguration `importMode` auf `'dynamic'` oder `'fetch'` ein:
+
+```ts fileName="intlayer.config.ts"
+export default {
+  dictionary: {
+    importMode: "dynamic", // "static" | "dynamic" | "fetch"
+  },
+};
+```
+
+Zur Build-Zeit scannen `@intlayer/swc` und `@intlayer/babel` Ihre Dateien und ersetzen `useIntlayer` / `getIntlayer`-Aufrufe durch tree-shakeable Wrapper (`useDictionary` / `useDictionaryDynamic`). Nur der für das ausgewählte Collection-Element, die Variante oder das Locale erforderliche Inhalt wird geladen, wodurch verhindert wird, dass Ihr Produktions-Bundle ungenutzte Übersetzungen enthält.
+
+---
+
+## Migrationshinweise von v8
+
+Wenn Sie von v8 upgraden, beachten Sie, dass v9 keine Breaking Changes enthält. Hier sind jedoch die wichtigsten Änderungen:
+
+- **Locales & Dialects**: Wenn Sie externe i18n-Abhängigkeiten verwenden, fügen Sie deren entsprechende Kompatibilitätsadapter-Plugins in Ihrer Konfiguration oder Ihrem Bundler-Setup hinzu, um Imports automatisch umzuschreiben.
+- **Custom Selectors**: Beim Aufruf von `useIntlayer` ist der zweite Parameter nun für ein Options-Objekt reserviert, das `{ locale, item, variant, id }` enthält. Wenn Sie zuvor direkt einen Locale-String übergeben haben, können Sie dies weiterhin tun, aber die Verwendung des Options-Objekts wird für erweiterte Auswahlen empfohlen.
+
+---
+
+## Nützliche Links
+
+- [Leitfaden für Compat Adapter Packages](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/compat/index.md)
+- [Dynamische Dictionaries – Collections, Variants & Dynamic Records](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/dynamic_dictionaries/index.md)
+- [Konfigurationsreferenz](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/configuration.md)

package/docs/en/CI_CD.md

@@ -93,7 +93,7 @@ export default config;
 
 ```bash fileName=".husky/pre-push"
 npx intlayer build                          # To ensure dictionaries are up to date
-npx intlayer fill --unpushed --mode fill    # Only fill missing content, does not update existing ones
+npx intlayer fill --unpushed --mode complete    # Only fill missing content, does not update existing ones
 ```
 
 > For more information about Intlayer CLI commands and their usage, refer to the [CLI documentation](https://github.com/aymericzip/intlayer/blob/main/docs/docs/en/cli/index.md).
@@ -103,11 +103,11 @@ npx intlayer fill --unpushed --mode fill    # Only fill missing content, does no
 ```bash fileName=".husky/pre-push"
 # App 1
 npx intlayer build --base-dir ./app1
-npx intlayer fill --base-dir ./app1 --unpushed --mode fill
+npx intlayer fill --base-dir ./app1 --unpushed --mode complete
 
 # App 2
 npx intlayer build --base-dir ./app2
-npx intlayer fill --base-dir ./app2 --unpushed --mode fill
+npx intlayer fill --base-dir ./app2 --unpushed --mode complete
 ```
 
 ## Using GitHub Actions
@@ -135,8 +135,8 @@ jobs:
     runs-on: ubuntu-latest
     env:
       # OpenAI
-      AI_MODEL: openai
-      AI_PROVIDER: gpt-5-mini
+      AI_PROVIDER: openai
+      AI_MODEL: gpt-5-mini
       AI_API_KEY: ${{ secrets.AI_API_KEY }}
 
     steps:
@@ -167,10 +167,10 @@ jobs:
 
       # Step 6: Use AI to automatically fill missing translations
       - name: 🤖 Auto-fill missing translations
-        run: npx intlayer fill --git-diff --mode fill --provider $AI_PROVIDER --model $AI_MODEL --api-key $AI_API_KEY
+        run: npx intlayer fill --git-diff --mode complete --provider $AI_PROVIDER --model $AI_MODEL --api-key $AI_API_KEY
 
       # Step 7: Check if there are changes and commit them
-      - name: � Check for changes
+      - name: 🔍 Check for changes
         id: check-changes
         run: |
           if [ -n "$(git status --porcelain)" ]; then

package/docs/en/cli/ci.md

@@ -128,18 +128,72 @@ bun x intlayer ci fill --verbose --mode complete
 
 ### Use in CI/CD pipelines
 
-In your CI/CD configuration (e.g., GitHub Actions, GitLab CI), set the `INTLAYER_PROJECT_CREDENTIALS` as a secret:
+Running `intlayer init` scaffolds two ready-to-use GitHub Actions workflows for you (see [Scaffolded GitHub Actions](#scaffolded-github-actions) below). The example here shows the equivalent setup using the `ci` command for a monorepo, where credentials are injected per project from `INTLAYER_PROJECT_CREDENTIALS`.
+
+> **AI access**: The `fill` command needs AI access to generate translations. The credentials injected by `ci` from `INTLAYER_PROJECT_CREDENTIALS` (Intlayer CMS access keys) grant AI access through the Intlayer backend, so no separate AI provider key is required. If you prefer to use your own provider key instead, pass `--provider`, `--model`, and `--api-key` to `intlayer ci fill`. The `test` command does not require AI access.
+
+```yaml fileName=".github/workflows/intlayer-ci.yml"
+name: Intlayer CI
+
+on:
+  pull_request:
+    branches:
+      - main
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  intlayer:
+    runs-on: ubuntu-latest
+    env:
+      # CMS access keys per project. They also grant AI access for `fill`.
+      INTLAYER_PROJECT_CREDENTIALS: ${{ secrets.INTLAYER_PROJECT_CREDENTIALS }}
+    steps:
+      - name: ⬇️ Checkout repository
+        uses: actions/checkout@v4
+        with:
+          persist-credentials: true
+          fetch-depth: 0
+
+      - name: 🟢 Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: 📦 Install dependencies
+        run: npm ci
+
+      - name: 🤖 Fill missing translations
+        run: npx intlayer ci fill --git-diff --mode complete
+
+      - name: 🧪 Test for missing translations
+        run: npx intlayer ci test
+```
+
+## Scaffolded GitHub Actions
+
+When you run `intlayer init`, Intlayer detects your package manager (npm, yarn, pnpm, or bun) and scaffolds two GitHub Actions workflows under `.github/workflows/`, with commands matching that package manager:
 
-```yaml
-# GitHub Actions example
-env:
-  INTLAYER_PROJECT_CREDENTIALS: ${{ secrets.INTLAYER_PROJECT_CREDENTIALS }}
+- **`intlayer-fill.yml`** — On every pull request, builds the dictionaries and runs `intlayer fill --git-diff --mode complete` to generate missing translations for the changed dictionaries, then commits the result back to the PR branch.
+- **`intlayer-test.yml`** — On every pull request, builds the dictionaries and runs `intlayer test`, failing the check when required locales are missing translations.
 
-steps:
-  - name: Fill dictionaries
-    run: npx intlayer ci fill
+Existing workflow files are never overwritten. To skip scaffolding entirely, run:
+
+```bash
+npx intlayer init --no-github-actions
 ```
 
+### Providing AI access to the fill workflow
+
+The scaffolded `intlayer-fill.yml` requires AI access. Two options are available (configured in the workflow's `env` block):
+
+1. **Your own AI provider key** — Add an `AI_API_KEY` secret in your repository settings (Settings → Secrets and variables → Actions). The workflow forwards it via `--provider`, `--model`, and `--api-key`.
+2. **Intlayer CMS access keys** — Add `INTLAYER_CLIENT_ID` and `INTLAYER_CLIENT_SECRET` secrets and wire them into your `intlayer.config` `editor` section. CMS access keys grant AI access through the Intlayer backend.
+
+The `intlayer-test.yml` workflow does not require any AI access.
+
 ## Error Handling
 
 - If `INTLAYER_PROJECT_CREDENTIALS` is not set, the command will exit with an error.