@intlayer/docs 7.0.3 → 7.0.4

package/blog/de/intlayer_with_next-intl.md

@@ -1,393 +1,112 @@
 ---
 createdAt: 2025-01-02
-updatedAt: 2025-06-29
-title: Intlayer und next-intl
-description: Integrieren Sie Intlayer mit next-intl für die Internationalisierung (i18n) einer React-App
-keywords:
-  - next-intl
-  - Intlayer
-  - Internationalisierung
-  - Dokumentation
-  - Next.js
-  - JavaScript
-  - React
+updatedAt: 2025-10-29
+title: Wie Sie Ihre next-intl JSON-Übersetzungen mit Intlayer automatisieren
+description: Automatisieren Sie Ihre JSON-Übersetzungen mit Intlayer und next-intl für eine verbesserte Internationalisierung in Next.js-Anwendungen.
 slugs:
   - blog
   - intlayer-with-next-intl
+history:
+  - version: 7.0.0
+    date: 2025-10-29
+    changes: Wechsel zum syncJSON-Plugin
 ---
 
-# Next.js Internationalisierung (i18n) mit next-intl und Intlayer
+# Wie Sie Ihre next-intl JSON-Übersetzungen mit Intlayer automatisieren
 
-Sowohl next-intl als auch Intlayer sind Open-Source-Internationalisierungsframeworks (i18n), die für Next.js-Anwendungen entwickelt wurden. Sie werden häufig für die Verwaltung von Übersetzungen, Lokalisierung und Sprachwechsel in Softwareprojekten eingesetzt.
+## Was ist Intlayer?
 
-Sie teilen drei Hauptkonzepte:
+**Intlayer** ist eine innovative, Open-Source-Internationalisierungsbibliothek, die entwickelt wurde, um die Schwächen traditioneller i18n-Lösungen zu beheben. Sie bietet einen modernen Ansatz für das Content-Management in Next.js-Anwendungen.
 
-1. **Inhaltsdeklaration**: Die Methode zur Definition des übersetzbaren Inhalts Ihrer Anwendung.
+Sehen Sie einen konkreten Vergleich mit next-intl in unserem Blogbeitrag [next-i18next vs. next-intl vs. Intlayer](https://github.com/aymericzip/intlayer/blob/main/docs/blog/de/next-i18next_vs_next-intl_vs_intlayer.md).
 
-   - Genannt `content declaration file` in Intlayer, welches eine JSON-, JS- oder TS-Datei sein kann, die die strukturierten Daten exportiert. Siehe [Intlayer-Dokumentation](https://intlayer.org/fr/doc/concept/content) für weitere Informationen.
-   - Genannt `messages` oder `locale messages` in next-intl, normalerweise in JSON-Dateien. Siehe [next-intl-Dokumentation](https://github.com/amannn/next-intl) für weitere Informationen.
+## Warum Intlayer mit next-intl kombinieren?
 
-2. **Hilfsprogramme**: Werkzeuge zum Erstellen und Interpretieren von Inhaltsdeklarationen in der Anwendung, wie `useIntlayer()` oder `useLocale()` für Intlayer und `useTranslations()` für next-intl.
+Während Intlayer eine ausgezeichnete eigenständige i18n-Lösung bietet (siehe unseren [Next.js-Integrationsleitfaden](https://github.com/aymericzip/intlayer/blob/main/docs/docs/de/intlayer_with_nextjs_16.md)), möchten Sie es möglicherweise aus mehreren Gründen mit next-intl kombinieren:
 
-3. **Plugins und Middleware**: Funktionen zur Verwaltung von URL-Weiterleitungen, Optimierung der Bundles und mehr – z.B. `intlayerMiddleware` für Intlayer oder [`createMiddleware`](https://github.com/amannn/next-intl) für next-intl.
+1. **Bestehender Codebestand**: Sie haben eine etablierte next-intl-Implementierung und möchten schrittweise zur verbesserten Entwicklererfahrung von Intlayer migrieren.
+2. **Altsystemanforderungen**: Ihr Projekt erfordert Kompatibilität mit bestehenden next-intl-Plugins oder Workflows.
+3. **Teamvertrautheit**: Ihr Team ist mit next-intl vertraut, möchte aber ein besseres Content-Management.
 
-## Intlayer vs. next-intl: Wichtige Unterschiede
+**Dafür kann Intlayer als Adapter für next-intl implementiert werden, um Ihre JSON-Übersetzungen in CLI- oder CI/CD-Pipelines zu automatisieren, Ihre Übersetzungen zu testen und mehr.**
 
-Für eine tiefere Analyse, wie Intlayer mit anderen i18n-Bibliotheken für Next.js (wie next-intl) verglichen wird, lesen Sie den [next-i18next vs. next-intl vs. Intlayer Blogbeitrag](https://github.com/aymericzip/intlayer/blob/main/docs/blog/de/i18next_vs_next-intl_vs_intlayer.md).
+Dieser Leitfaden zeigt Ihnen, wie Sie das überlegene Content-Deklarationssystem von Intlayer nutzen und gleichzeitig die Kompatibilität mit next-intl beibehalten.
 
-## Wie man next-intl-Nachrichten mit Intlayer generiert
+## Inhaltsverzeichnis
 
-### Warum Intlayer mit next-intl verwenden?
+<TOC/>
 
-Intlayer-Inhaltsdeklarationsdateien bieten im Allgemeinen eine bessere Entwicklererfahrung. Sie sind flexibler und wartbarer aufgrund zweier Hauptvorteile:
+## Schritt-für-Schritt-Anleitung zur Einrichtung von Intlayer mit next-intl
 
-1. **Flexibele Platzierung**: Sie können eine Intlayer-Inhaltsdeklarationsdatei überall im Dateibaum Ihrer Anwendung platzieren. Das erleichtert das Umbenennen oder Löschen von Komponenten, ohne ungenutzte oder nicht mehr benötigte Nachrichten-Dateien zu hinterlassen.
+### Schritt 1: Abhängigkeiten installieren
 
-   Beispiel-Dateistrukturen:
-
-   ```bash codeFormat="typescript"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.ts # Inhaltsdeklarationsdatei
-               └── index.tsx
-   ```
-
-   ```bash codeFormat="esm"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.mjs # Inhaltsdeklarationsdatei
-               └── index.mjx
-   ```
-
-   ```bash codeFormat="cjs"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.cjs # Inhaltsdeklarationsdatei
-               └── index.cjx
-   ```
-
-   ```bash codeFormat="json"
-   .
-   └── src
-       └── components
-           └── MyComponent
-               ├── index.content.json # Inhaltsdeklarationsdatei
-               └── index.jsx
-   ```
-
-2. **Zentralisierte Übersetzungen**: Intlayer speichert alle Übersetzungen in einer einzigen Inhaltsdeklaration, sodass keine Übersetzung fehlt. In TypeScript-Projekten werden fehlende Übersetzungen automatisch als Typfehler markiert, was den Entwicklern sofortiges Feedback gibt.
-
-### Installation
-
-Um Intlayer und next-intl zusammen zu verwenden, installieren Sie beide Bibliotheken:
+Installieren Sie die erforderlichen Pakete:
 
 ```bash packageManager="npm"
-npm install intlayer next-intl
-```
-
-```bash packageManager="yarn"
-yarn add intlayer next-intl
+npm install intlayer @intlayer/sync-json-plugin
 ```
 
 ```bash packageManager="pnpm"
-pnpm add intlayer next-intl
+pnpm add intlayer @intlayer/sync-json-plugin
 ```
 
-### Konfigurieren von Intlayer zur Ausgabe von next-intl-Nachrichten
-
-> **Hinweis:** Die Ausgabe von Nachrichten von Intlayer für next-intl kann geringfügige Unterschiede in der Struktur mit sich bringen. Halten Sie, wenn möglich, einen nur Intlayer- oder nur next-intl-Workflow, um die Integration zu vereinfachen. Wenn Sie next-intl-Nachrichten von Intlayer generieren müssen, befolgen Sie die folgenden Schritte.
-
-Erstellen oder aktualisieren Sie eine `intlayer.config.ts`-Datei (oder `.mjs` / `.cjs`) im Stammverzeichnis Ihres Projekts:
-
-```typescript fileName="intlayer.config.ts" codeFormat="typescript"
-import { Locales, type IntlayerConfig } from "intlayer";
-
-const config: IntlayerConfig = {
-  internationalization: {
-    locales: [Locales.GERMAN, Locales.FRENCH, Locales.SPANISH],
-    defaultLocale: Locales.GERMAN,
-  },
-  content: {
-    dictionaryOutput: ["next-intl"], // Verwenden Sie die next-intl-Ausgabe
-    nextIntlMessagesDir: "./intl/messages", // Wo die next-intl-Nachrichten gespeichert werden
-  },
-};
-
-export default config;
+```bash packageManager="yarn"
+yarn add intlayer @intlayer/sync-json-plugin
 ```
 
-```javascript fileName="intlayer.config.mjs" codeFormat="esm"
-import { Locales } from "intlayer";
+**Paketbeschreibungen:**
 
-/** @type {import('intlayer').IntlayerConfig} */
-const config = {
-  internationalization: {
-    locales: [Locales.GERMAN, Locales.FRENCH, Locales.SPANISH],
-    defaultLocale: Locales.GERMAN,
-  },
-  content: {
-    dictionaryOutput: ["react-intl"],
-    nextIntlMessagesDir: "./intl/messages",
-  },
-};
+- **intlayer**: Kernbibliothek für Internationalisierungsmanagement, Content-Deklaration und Build-Prozesse
+- **@intlayer/sync-json-plugin**: Plugin zum Exportieren von Intlayer-Content-Deklarationen in ein next-intl-kompatibles JSON-Format
 
-export default config;
-```
+### Schritt 2: Implementieren Sie das Intlayer-Plugin zum Verpacken des JSON
 
-```javascript fileName="intlayer.config.cjs" codeFormat="commonjs"
-const { Locales } = require("intlayer");
+Erstellen Sie eine Intlayer-Konfigurationsdatei, um Ihre unterstützten Sprachen zu definieren:
 
-/** @type {import('intlayer').IntlayerConfig} */
-const config = {
-  internationalization: {
-    locales: [Locales.GERMAN, Locales.FRENCH, Locales.SPANISH],
-    defaultLocale: Locales.GERMAN,
-  },
-  content: {
-    dictionaryOutput: ["next-intl"],
-    nextIntlMessagesDir: "./intl/messages",
-  },
-};
-
-module.exports = config;
-```
-
-### Inhaltsdeklaration
+**Wenn Sie auch JSON-Wörterbücher für next-intl exportieren möchten**, fügen Sie das `syncJSON`-Plugin hinzu:
 
-Nachfolgend Beispiele für Inhaltsdeklarationsdateien in mehreren Formaten. Intlayer wird diese in Nachrichten-Dateien kompilieren, die next-intl konsumieren kann.
-
-```typescript fileName="**/*.content.ts" contentDeclarationFormat="typescript"
-import { t, type Dictionary } from "intlayer";
+```typescript fileName="intlayer.config.ts"
+import { Locales, type IntlayerConfig } from "intlayer";
+import { syncJSON } from "@intlayer/sync-json-plugin";
 
-const content = {
-  key: "my-component",
-  content: {
-    helloWorld: t({
-      de: "Hallo Welt",
-      fr: "Bonjour le monde",
-      es: "Hola Mundo",
-    }),
+const config: IntlayerConfig = {
+  internationalization: {
+    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],
+    defaultLocale: Locales.ENGLISH,
   },
-} satisfies Dictionary;
-
-export default content;
-```
-
-```javascript fileName="**/*.content.mjs" contentDeclarationFormat="esm"
-import { t } from "intlayer";
-
-/** @type {import('intlayer').Dictionary} */
-const content = {
-  key: "my-component",
-  content: {
-    helloWorld: t({
-      de: "Hallo Welt",
-      fr: "Bonjour le monde",
-      es: "Hola Mundo",
+  plugins: [
+    syncJSON({
+      source: ({ key, locale }) => `./messages/${locale}/${key}.json`,
     }),
-  },
+  ],
 };
 
-export default content;
-```
-
-```javascript fileName="**/*.content.cjs" contentDeclarationFormat="commonjs"
-const { t } = require("intlayer");
-
-module.exports = {
-  key: "my-component",
-  content: {
-    helloWorld: t({
-      de: "Hallo Welt",
-      fr: "Bonjour le monde",
-      es: "Hola Mundo",
-    }),
-  },
-};
+export default config;
 ```
 
-```json fileName="**/*.content.json" contentDeclarationFormat="json"
-{
-  "$schema": "https://intlayer.org/schema.json",
-  "key": "my-component",
-  "content": {
-    "helloWorld": {
-      "nodeType": "translation",
-      "translation": {
-        "de": "Hallo Welt",
-        "fr": "Bonjour le monde",
-        "es": "Hola Mundo"
-      }
-    }
-  }
-}
-```
+Das `syncJSON`-Plugin verpackt das JSON automatisch. Es liest und schreibt die JSON-Dateien, ohne die Inhaltsarchitektur zu verändern.
 
-### Erstellen der next-intl-Nachrichten
+Wenn Sie möchten, dass dieses JSON zusammen mit Intlayer-Content-Deklarationsdateien (`.content`-Dateien) koexistiert, geht Intlayer folgendermaßen vor:
 
-Um die Nachrichten-Dateien für next-intl zu erstellen, führen Sie aus:
+    1. Lädt sowohl JSON- als auch Content-Deklarationsdateien und transformiert sie in ein Intlayer-Wörterbuch.
 
-```bash packageManager="npm"
-npx intlayer dictionaries build
-```
+2. Wenn es Konflikte zwischen den JSON- und den Inhaltsdeklarationsdateien gibt, wird Intlayer alle Wörterbücher zusammenführen. Dies hängt von der Priorität der Plugins und der der Inhaltsdeklarationsdatei ab (alle sind konfigurierbar).
 
-```bash packageManager="yarn"
-yarn intlayer build
-```
+Wenn Änderungen über die CLI zur Übersetzung des JSON vorgenommen werden oder das CMS verwendet wird, aktualisiert Intlayer die JSON-Datei mit den neuen Übersetzungen.
 
-```bash packageManager="pnpm"
-pnpm intlayer build
-```
+## Git-Konfiguration
 
-Dies generiert Ressourcen im `./intl/messages`-Verzeichnis (wie in `intlayer.config.*` konfiguriert). Die erwartete Ausgabe:
-
-```bash
-.
-└── intl
-    └── messages
-       └── de
-           └── my-content.json
-       └── fr
-           └── my-content.json
-       └── es
-           └── my-content.json
-```
+Es wird empfohlen, automatisch generierte Intlayer-Dateien zu ignorieren:
 
-Jede Datei enthält kompilierte Nachrichten aus allen Intlayer-Inhaltsdeklarationen. Die obersten Schlüssel entsprechen typischerweise Ihren `content.key`-Feldern.
-
-### Verwendung von next-intl in Ihrer Next.js-App
-
-> Für weitere Details siehe die offiziellen [next-intl-Nutzungsdokumente](https://github.com/amannn/next-intl#readme).
-
-1. **Middleware erstellen (optional):**  
-   Wenn Sie die automatische Lokalisierung oder Weiterleitung verwalten möchten, verwenden Sie next-intls [createMiddleware](https://github.com/amannn/next-intl#createMiddleware).
-
-   ```typescript fileName="middleware.ts"
-   import createMiddleware from "next-intl/middleware";
-   import { NextResponse } from "next/server";
-
-   export default createMiddleware({
-     locales: ["de", "fr", "es"],
-     defaultLocale: "de",
-   });
-
-   export const config = {
-     matcher: ["/((?!api|_next|.*\\..*).*)"],
-   };
-   ```
-
-2. **Erstellen Sie eine `layout.tsx` oder `_app.tsx`, um Nachrichten zu laden:**  
-   Wenn Sie den App-Router verwenden (Next.js 13+), erstellen Sie ein Layout:
-
-   ```typescript fileName="app/[locale]/layout.tsx"
-   import { NextIntlClientProvider } from 'next-intl';
-   import { notFound } from 'next/navigation';
-   import React, { ReactNode } from 'react';
-
-
-   export default async function RootLayout({
-     children,
-     params
-   }: {
-     children: ReactNode;
-     params: { locale: string };
-   }) {
-     let messages;
-     try {
-       messages = (await import(`../../intl/messages/${params.locale}.json`)).default;
-     } catch (error) {
-       notFound();
-     }
-
-     return (
-       <html lang={params.locale}>
-         <body>
-           <NextIntlClientProvider locale={params.locale} messages={messages}>
-             {children}
-           </NextIntlClientProvider>
-         </body>
-       </html>
-     );
-   }
-   ```
-
-   Wenn Sie den Pages-Router verwenden (Next.js 12 oder früher), laden Sie die Nachrichten in `_app.tsx`:
-
-   ```typescript fileName="pages/_app.tsx"
-   import type { AppProps } from 'next/app';
-   import { NextIntlProvider } from 'next-intl';
-
-   function MyApp({ Component, pageProps }: AppProps) {
-     return (
-       <NextIntlProvider locale={pageProps.locale} messages={pageProps.messages}>
-         <Component {...pageProps} />
-       </NextIntlProvider>
-     );
-   }
-
-   export default MyApp;
-   ```
-
-3. **Nachrichten serverseitig abrufen (Pages Router-Beispiel):**
-
-   ```typescript fileName="pages/index.tsx"
-   import { GetServerSideProps } from "next";
-   import HomePage from "../components/HomePage";
-
-   export default HomePage;
-
-   export const getServerSideProps: GetServerSideProps = async ({ locale }) => {
-     const messages = (await import(`../intl/messages/${locale}.json`)).default;
-
-     return {
-       props: {
-         locale,
-         messages,
-       },
-     };
-   };
-   ```
-
-### Verwendung von Inhalten in Next.js-Komponenten
-
-Sobald die Nachrichten in next-intl geladen sind, können Sie sie in Ihren Komponenten über den `useTranslations()`-Hook verwenden:
-
-```typescript fileName="src/components/MyComponent/index.tsx" codeFormat="typescript"
-import type { FC } from "react";
-import { useTranslations } from 'next-intl';
-
-const MyComponent: FC = () => {
-  const t = useTranslations('my-component');
-  // 'my-component' entspricht dem Inhaltskey in Intlayer
-
-  return (
-    <div>
-      <h1>{t('helloWorld')}</h1>
-    </div>
-  );
-};
-
-export default MyComponent;
+```plaintext fileName=".gitignore"
+# Dateien, die von Intlayer generiert werden, ignorieren
+.intlayer
 ```
 
-```jsx fileName="src/components/MyComponent/index.jsx" codeFormat="esm"
-import { useTranslations } from "next-intl";
+Diese Dateien können während Ihres Build-Prozesses neu generiert werden und müssen nicht in die Versionskontrolle aufgenommen werden.
 
-export default function MyComponent() {
-  const t = useTranslations("my-component");
+### VS Code Erweiterung
 
-  return (
-    <div>
-      <h1>{t("helloWorld")}</h1>
-    </div>
-  );
-}
-```
+Für eine verbesserte Entwicklererfahrung installieren Sie die offizielle **Intlayer VS Code Erweiterung**:
 
-**Das war's!** Jedes Mal, wenn Sie Intlayer-Inhaltsdeklarationsdateien aktualisieren oder hinzufügen, führen Sie den Befehl `intlayer build` erneut aus, um Ihre next-intl JSON-Nachrichten neu zu generieren. next-intl wird den aktualisierten Inhalt automatisch erkennen.
+[Installation aus dem VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=intlayer.intlayer-vs-code-extension)