@intlayer/docs 5.5.8

package/de/vs_code_extension.md

@@ -0,0 +1,139 @@
+# Offizielle VS Code Erweiterung für Intlayer
+
+## Übersicht
+
+**Intlayer** ist die offizielle Visual Studio Code Erweiterung für **Intlayer**, entwickelt, um die Entwicklererfahrung bei der Arbeit mit lokalisierten Inhalten in **React, Next.js und JavaScript** Projekten zu verbessern.
+
+Mit dieser Erweiterung können Entwickler **schnell zu ihren Inhaltswörterbüchern navigieren**, Lokalisierungsdateien verwalten und ihren Workflow mit leistungsstarken Automatisierungsbefehlen optimieren.
+
+![Intlayer VS Code Extension](https://github.com/aymericzip/intlayer/blob/main/docs/assets/vs_code_extension_demo.gif)
+
+Erweiterungslink: [https://marketplace.visualstudio.com/items?itemName=Intlayer.intlayer-vs-code-extension](https://marketplace.visualstudio.com/items?itemName=Intlayer.intlayer-vs-code-extension)
+
+## Funktionen
+
+### Sofortige Navigation
+
+**Gehe-zu-Definition-Unterstützung** – Verwenden Sie `Cmd+Klick` (Mac) oder `Ctrl+Klick` (Windows/Linux) auf einen `useIntlayer` Schlüssel, um die entsprechende Inhaltsdatei sofort zu öffnen.  
+**Nahtlose Integration** – Funktioniert mühelos mit **react-intlayer** und **next-intlayer** Projekten.  
+**Mehrsprachige Unterstützung** – Unterstützt lokalisierte Inhalte in verschiedenen Sprachen.  
+**VS Code Integration** – Integriert sich reibungslos in die Navigation und Befehlsübersicht von VS Code.
+
+### Wörterbuchverwaltungsbefehle
+
+Verwalten Sie Ihre Inhaltswörterbücher direkt in VS Code:
+
+- **Wörterbücher erstellen** (`extension.buildDictionaries`) – Generieren Sie Inhaltsdateien basierend auf Ihrer Projektstruktur.
+- **Wörterbücher hochladen** (`extension.pushDictionaries`) – Laden Sie die neuesten Wörterbuchinhalte in Ihr Repository hoch.
+- **Wörterbücher herunterladen** (`extension.pullDictionaries`) – Synchronisieren Sie die neuesten Wörterbuchinhalte aus Ihrem Repository mit Ihrer lokalen Umgebung.
+
+### Inhaltsdeklarationsgenerator
+
+Erstellen Sie mühelos strukturierte Wörterbuchdateien in verschiedenen Formaten:
+
+- **TypeScript (`.ts`)** – `extension.createDictionaryFile.ts`
+- **ES Module (`.esm`)** – `extension.createDictionaryFile.esm`
+- **CommonJS (`.cjs`)** – `extension.createDictionaryFile.cjs`
+- **JSON (`.json`)** – `extension.createDictionaryFile.json`
+
+## Installation
+
+Sie können **Intlayer** direkt aus dem VS Code Marketplace installieren:
+
+1. Öffnen Sie **VS Code**.
+2. Gehen Sie zum **Erweiterungs-Marktplatz**.
+3. Suchen Sie nach **"Intlayer"**.
+4. Klicken Sie auf **Installieren**.
+
+Alternativ können Sie es über die Befehlszeile installieren:
+
+```sh
+code --install-extension intlayer
+```
+
+## Verwendung
+
+### Schnelle Navigation
+
+1. Öffnen Sie ein Projekt, das **react-intlayer** verwendet.
+2. Suchen Sie einen Aufruf von `useIntlayer()`, wie zum Beispiel:
+
+   ```tsx
+   const content = useIntlayer("app");
+   ```
+
+3. **Cmd-Klick** (`⌘+Klick` auf macOS) oder **Ctrl-Klick** (auf Windows/Linux) auf den Schlüssel (z. B. `"app"`).
+4. VS Code öffnet automatisch die entsprechende Wörterbuchdatei, z. B. `src/app.content.ts`.
+
+### Verwaltung von Inhaltswörterbüchern
+
+#### Wörterbücher erstellen
+
+Generieren Sie alle Wörterbuchinhaltsdateien mit:
+
+```sh
+Cmd + Shift + P (macOS) / Ctrl + Shift + P (Windows/Linux)
+```
+
+Suchen Sie nach **Wörterbücher erstellen** und führen Sie den Befehl aus.
+
+#### Wörterbücher hochladen
+
+Laden Sie die neuesten Wörterbuchinhalte hoch:
+
+1. Öffnen Sie die **Befehlsübersicht**.
+2. Suchen Sie nach **Wörterbücher hochladen**.
+3. Wählen Sie die Wörterbücher aus, die hochgeladen werden sollen, und bestätigen Sie.
+
+#### Wörterbücher herunterladen
+
+Synchronisieren Sie die neuesten Wörterbuchinhalte:
+
+1. Öffnen Sie die **Befehlsübersicht**.
+2. Suchen Sie nach **Wörterbücher herunterladen**.
+3. Wählen Sie die Wörterbücher aus, die heruntergeladen werden sollen.
+
+### Anpassung der Wörterbuchdateipfade
+
+Standardmäßig folgt die Erweiterung der Standardprojektstruktur von **Intlayer**. Sie können jedoch benutzerdefinierte Pfade konfigurieren:
+
+1. Öffnen Sie **Einstellungen (`Cmd + ,` auf macOS / `Ctrl + ,` auf Windows/Linux)`**.
+2. Suchen Sie nach `Intlayer`.
+3. Passen Sie die Einstellung für den Inhaltsdateipfad an.
+
+## Entwicklung & Beitrag
+
+Möchten Sie beitragen? Wir freuen uns über Beiträge aus der Community!
+
+Repo-URL: https://github.com/aymericzip/intlayer-vs-code-extension
+
+### Erste Schritte
+
+Klonen Sie das Repository und installieren Sie die Abhängigkeiten:
+
+```sh
+git clone https://github.com/aymericzip/intlayer-vs-code-extension.git
+cd intlayer-vs-code-extension
+npm install
+```
+
+> Verwenden Sie den `npm` Paketmanager für die Kompatibilität mit dem `vsce` Paket, um die Erweiterung zu erstellen und zu veröffentlichen.
+
+### Im Entwicklungsmodus ausführen
+
+1. Öffnen Sie das Projekt in **VS Code**.
+2. Drücken Sie `F5`, um ein neues **Erweiterungs-Entwicklungsfenster** zu starten.
+
+### Einen Pull Request einreichen
+
+Wenn Sie die Erweiterung verbessern, reichen Sie einen PR auf [GitHub](https://github.com/aymericzip/intlayer-vs-code-extension) ein.
+
+## Feedback & Probleme
+
+Haben Sie einen Fehler gefunden oder eine Funktionsanfrage? Öffnen Sie ein Issue in unserem **GitHub Repository**:
+
+[GitHub Issues](https://github.com/aymericzip/intlayer-vs-code-extension/issues)
+
+## Lizenz
+
+Intlayer wird unter der **MIT-Lizenz** veröffentlicht.

package/en/CI_CD.md

@@ -0,0 +1,149 @@
+# Auto-Generate Translations in a CI/CD Pipeline
+
+Intlayer allows the automatic generation of translations for your content declaration files. There are multiple ways to achieve this depending on your workflow.
+
+## Using the CMS
+
+With Intlayer, you can adopt a workflow where only a single locale is declared locally, while all translations are managed remotely through the CMS. This allows content and translations to be completely detached from the codebase, offering more flexibility for content editors and enabling hot content reloading (no need to rebuild the application to apply changes).
+
+### Example Configuration
+
+```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: {
+    dictionaryPriorityStrategy: "distant_first", // Remote content takes priority
+
+    applicationURL: process.env.APPLICATION_URL, // Application URL used by the CMS
+
+    clientId: process.env.INTLAYER_CLIENT_ID, // CMS credentials
+    clientSecret: process.env.INTLAYER_CLIENT_SECRET,
+  },
+  ai: {
+    applicationContext: "This is a test application", // Helps ensure consistent translation generation
+  },
+};
+
+export default config;
+```
+
+To learn more about the CMS, refer to the [official documentation](https://github.com/aymericzip/intlayer/blob/main/docs/en/intlayer_CMS.md).
+
+## Using Husky
+
+You can integrate translation generation into your local Git workflow using [Husky](https://typicode.github.io/husky/).
+
+### Example Configuration
+
+```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 are handled remotely
+    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, // Use your own API key
+
+    applicationContext: "This is a test application", // Helps ensure consistent translation generation
+  },
+};
+
+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
+```
+
+> For more information about Intlayer CLI commands and their usage, refer to the [CLI documentation](https://github.com/aymericzip/intlayer/blob/main/docs/en/intlayer_cli.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"
+# App 1
+npx intlayer build --base-dir ./app1
+npx intlayer fill --base-dir ./app1 --unpushed --mode fill
+
+# App 2
+npx intlayer build --base-dir ./app2
+npx intlayer fill --base-dir ./app2 --unpushed --mode fill
+```
+
+## Using GitHub Actions
+
+Intlayer provides a CLI command to autofill and review dictionary content. This can be integrated into your CI/CD workflow using GitHub Actions.
+
+```yaml fileName=".github/workflows/intlayer-translate.yml"
+name: Intlayer Auto-Fill
+on:
+  push:
+    branches: [ main ]
+    paths:
+      - 'src/**'
+  pull_request:
+    branches: [ main ]
+    paths:
+      - 'src/**'
+  workflow_dispatch: {}
+
+concurrency:
+  group: 'autofill-${{ github.ref }}'
+  cancel-in-progress: true
+
+jobs:
+  autofill:
+    runs-on: ubuntu-latest
+    env:
+      INTLAYER_CLIENT_ID: ${{ secrets.INTLAYER_CLIENT_ID }}
+      INTLAYER_CLIENT_SECRET: ${{ secrets.INTLAYER_CLIENT_SECRET }}
+      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+
+    steps:
+      - name: ⬇️ Checkout repository
+        uses: actions/checkout@v3
+        with:
+          persist-credentials: true
+
+      - name: 🟢 Set up Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: 20
+
+      - name: 📦 Install dependencies
+        run: npm ci
+
+      - name: ⚙️ Build Intlayer project
+        run: npx intlayer build
+
+      - name: 🤖 Auto-fill missing translations
+        run: npx intlayer fill --git-diff --mode fill
+
+      - name: 📤 Create or update translation PR
+        uses: peter-evans/create-pull-request@v4
+        with:
+          commit-message: chore: auto-fill missing translations [skip ci]
+          branch: auto-translations
+          title: chore: update missing translations
+          labels: translation, automated
+```
+
+> Same as for Husky, in the case of a monorepo, you can use the `--base-dir` argument to sequentially treat each app.
+
+> By default, the `--git-diff` argument filters dictionaries that include changes from base (default `origin/main`) to current branch (default: `HEAD`).
+
+> For more information about Intlayer CLI commands and their usage, refer to the [CLI documentation](https://github.com/aymericzip/intlayer/blob/main/docs/en/intlayer_cli.md).

package/en/autoFill.md

@@ -0,0 +1,157 @@
+# Autofill Content Declaration File Translations
+
+**Autofill content declaration files** are a way to speed up your development workflow.
+
+The autofill mechanism works through a _master-slave_ relationship between content declaration files. When the main (master) file is updated, Intlayer will automatically apply those changes to the derived (autofilled) declaration files.
+
+```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: "This is an example of content",
+  },
+} satisfies Dictionary;
+
+export default exampleContent;
+```
+
+Here is a [per-locale content declaration file](https://github.com/aymericzip/intlayer/blob/main/docs/en/per_locale_file.md) using the `autoFill` instruction.
+
+Then, when you run the following command:
+
+```bash
+npx intlayer fill --file 'src/components/example/example.content.ts'
+```
+
+Intlayer will automatically generate the derived declaration file at `src/components/example/example.content.json`, filling in all locales not already declared in the main file.
+
+```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",
+      },
+    },
+  },
+}
+```
+
+Afterward, both declaration files will be merged into a single dictionary, accessible using the standard `useIntlayer("example")` hook (react) / composable (vue).
+
+## Autofilled File Format
+
+The recommended format for autofilled declaration files is **JSON**, which helps avoid formatting constraints. However, Intlayer also supports `.ts`, `.js`, `.mjs`, `.cjs`, and other formats.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: "./example.filled.content.ts",
+  content: {
+    // Your content
+  },
+};
+```
+
+This will generate the file at:
+
+```
+src/components/example/example.filled.content.ts
+```
+
+> The generation of `.js`, `.ts`, and similar files works as follows:
+
+> - If the file already exists, Intlayer will parse it using the AST (Abstract Syntax Tree) to locate each field and insert any missing translations.
+
+> - If the file does not exist, Intlayer will generate it using the default content declaration file template.
+
+## Absolute Paths
+
+The `autoFill` field also supports absolute paths.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: "/messages/example.content.json",
+  content: {
+    // Your content
+  },
+};
+```
+
+This will generate the file at:
+
+```
+/messages/example.content.json
+```
+
+## Autogenerate Per-Locale Content Declaration Files
+
+The `autoFill` field also supports generation of **per-locale** content declaration files.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: {
+    fr: "./example.fr.content.json",
+    es: "./example.es.content.json",
+  },
+  content: {
+    // Your content
+  },
+};
+```
+
+This will generate two separate files:
+
+- `src/components/example/example.fr.content.json`
+- `src/components/example/example.es.content.json`
+
+## Filter Specific Locale Autofill
+
+Using an object for the `autoFill` field allows you to apply filters and generate only specific locale files.
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: {
+    fr: "./example.fr.content.json",
+  },
+  content: {
+    // Your content
+  },
+};
+```
+
+This will only generate the French translation file.
+
+## Path Variables
+
+You can use variables inside the `autoFill` path to dynamically resolve the target paths for the generated files.
+
+**Available variables:**
+
+- `{{locale}}` – Locale code (e.g. `fr`, `es`)
+- `{{key}}` – Dictionary key (e.g. `example`)
+
+```ts fileName="src/components/example/example.content.ts"
+const exampleContent = {
+  key: "example",
+  autoFill: "/messages/{{locale}}/{{key}}.content.json",
+  content: {
+    // Your content
+  },
+};
+```
+
+This will generate:
+
+- `/messages/fr/example.content.json`
+- `/messages/es/example.content.json`