Sync JSON (i18n-Brücken) - Sync JSON mit ICU / i18next-Unterstützung

Verwenden Sie Intlayer als Ergänzung zu Ihrem bestehenden i18n-Stack. Dieses Plugin hält Ihre JSON-Nachrichten mit den Intlayer-Wörterbüchern synchron, sodass Sie:

• i18next, next-intl, react-intl, vue-i18n, next-translate, nuxt-i18n, Solid-i18next, svelte-i18n usw. beibehalten können.
• Ihre Nachrichten mit Intlayer (CLI, CI, Anbieter, CMS) verwalten und übersetzen, ohne Ihre App umzustrukturieren.
• Tutorials und SEO-Inhalte für jedes Ökosystem bereitstellen und gleichzeitig Intlayer als JSON-Verwaltungsschicht vorschlagen.

Hinweise und aktueller Umfang:

• Die Externalisierung zum CMS funktioniert für Übersetzungen und klassischen Text.
• Noch keine Unterstützung für Einfügungen, Pluralformen/ICU oder erweiterte Laufzeitfunktionen anderer Bibliotheken.
• Der visuelle Editor wird für Ausgaben von Drittanbieter-i18n noch nicht unterstützt.

Wann Sie dieses Plugin verwenden sollten

• Sie verwenden bereits eine i18n-Bibliothek und speichern Nachrichten in JSON-Dateien.
• Sie möchten KI-unterstütztes Ausfüllen, Tests in CI und Content-Operationen durchführen, ohne Ihre Rendering-Laufzeit zu ändern.

Installation

pnpm add -D @intlayer/sync-json-plugin# odernpm i -D @intlayer/sync-json-plugin

Schnellstart

Fügen Sie das Plugin zu Ihrer intlayer.config.ts hinzu und verweisen Sie auf Ihre bestehende JSON-Struktur.

import { Locales, type IntlayerConfig } from "intlayer";import { syncJSON } from "@intlayer/sync-json-plugin";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],    defaultLocale: Locales.ENGLISH,  },  // Halten Sie Ihre aktuellen JSON-Dateien mit den Intlayer-Wörterbüchern synchron  plugins: [    syncJSON({      // Pro-Locale, pro-Namespace Layout (z.B. next-intl, i18next mit Namespaces)      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,    }),  ],};export default config;

Alternative: Einzelne Datei pro Locale (häufig bei i18next/react-intl Setups):

plugins: [  syncJSON({    source: ({ locale }) => `./locales/${locale}.json`,  }),];

Funktionsweise

• Lesen: Das Plugin entdeckt JSON-Dateien über Ihren source-Builder und lädt sie als Intlayer-Wörterbücher.
• Schreiben: Nach dem Build und Ausfüllen schreibt es die lokalisierten JSON-Dateien zurück an dieselben Pfade (mit einer abschließenden neuen Zeile, um Formatierungsprobleme zu vermeiden).
• Auto-Fill: Das Plugin deklariert einen autoFill-Pfad für jedes Wörterbuch. Das Ausführen von intlayer fill aktualisiert standardmäßig nur fehlende Übersetzungen in Ihren JSON-Dateien.

API:

syncJSON({  source: ({ key, locale }) => string, // erforderlich  location?: string, // optionales Label, Standard: "plugin"  priority?: number, // optionale Priorität zur Konfliktlösung, Standard: 0  format?: 'intlayer' | 'icu' | 'i18next', // optionaler Formatierer, verwendet für Intlayer-Runtime-Kompatibilität});

format ('intlayer' | 'icu' | 'i18next')

Gibt den Formatierer an, der für den Wörterbuchinhalt bei der Synchronisierung von JSON-Dateien verwendet werden soll. Dies ermöglicht die Verwendung verschiedener Nachrichtenformatierungssyntaxen, die mit der Intlayer-Runtime kompatibel sind.

• undefined: Es wird kein Formatierer verwendet, der JSON-Inhalt wird unverändert verwendet.
• 'intlayer': Der Standard-Intlayer-Formatierer (Standard).
• 'icu': Verwendet ICU-Nachrichtenformatierung (kompatibel mit Bibliotheken wie react-intl, vue-i18n).
• 'i18next': Verwendet i18next-Nachrichtenformatierung (kompatibel mit i18next, next-i18next, Solid-i18next).

Beachten Sie, dass die Verwendung eines Formatierers Ihren JSON-Inhalt bei Ein- und Ausgabe transformiert. Bei komplexen JSON-Regeln wie ICU-Pluralen kann das Parsing keine 1-zu-1-Zuordnung zwischen Ein- und Ausgabe garantieren. Wenn Sie die Intlayer-Runtime nicht verwenden, sollten Sie möglicherweise keinen Formatierer festlegen.

Beispiel:

syncJSON({  source: ({ key, locale }) => `./locales/${locale}/${key}.json`,  format: "i18next", // i18next-Formatierung für Kompatibilität verwenden}),

Mehrere JSON-Quellen und Priorität

Sie können mehrere syncJSON-Plugins hinzufügen, um verschiedene JSON-Quellen zu synchronisieren. Dies ist nützlich, wenn Sie mehrere i18n-Bibliotheken oder unterschiedliche JSON-Strukturen in Ihrem Projekt haben.

Prioritätssystem

Wenn mehrere Plugins denselben Wörterbuchschlüssel ansprechen, bestimmt der Parameter priority, welches Plugin Vorrang hat:

• Höhere Prioritätszahlen haben Vorrang vor niedrigeren
• Die Standardpriorität von .content-Dateien ist 0
• Die Standardpriorität von Plugin-Content-Dateien ist -1
• Plugins mit derselben Priorität werden in der Reihenfolge verarbeitet, in der sie in der Konfiguration erscheinen

import { Locales, type IntlayerConfig } from "intlayer";import { syncJSON } from "@intlayer/sync-json-plugin";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH, Locales.FRENCH],    defaultLocale: Locales.ENGLISH,  },  plugins: [    // Primäre JSON-Quelle (höchste Priorität)    syncJSON({      format: "i18next",      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,      location: "main-translations",      priority: 10,    }),    // Fallback-JSON-Quelle (niedrigere Priorität)    syncJSON({      format: "i18next",      source: ({ locale }) => `./fallback-locales/${locale}.json`,      location: "fallback-translations",      priority: 5,    }),    // Legacy-JSON-Quelle (niedrigste Priorität)    syncJSON({      format: "i18next",      source: ({ locale }) => `/my/other/app/legacy/${locale}/messages.json`,      location: "legacy-translations",      priority: 1,    }),  ],};export default config;

Konfliktlösung

Wenn derselbe Übersetzungsschlüssel in mehreren JSON-Quellen vorhanden ist:

1. Bestimmt das Plugin mit der höchsten Priorität den endgültigen Wert
2. Werden Quellen mit niedrigerer Priorität als Fallbacks für fehlende Schlüssel verwendet
3. Ermöglicht es Ihnen, Legacy-Übersetzungen beizubehalten und gleichzeitig schrittweise auf neue Strukturen umzusteigen

Integrationen

Nachfolgend sind gängige Zuordnungen aufgeführt. Belassen Sie Ihre Laufzeit unverändert; fügen Sie nur das Plugin hinzu.

i18next

Typische Dateistruktur: ./public/locales/{locale}/{namespace}.json oder ./locales/{locale}/{namespace}.json.

import { syncJSON } from "@intlayer/sync-json-plugin";export default {  plugins: [    syncJSON({      format: "i18next",      source: ({ key, locale }) => `./locales/${locale}/${key}.json`,    }),  ],};

next-intl

JSON-Nachrichten pro Locale (oft ./messages/{locale}.json) oder pro Namespace.

plugins: [  syncJSON({    source: ({ locale, key }) => `./messages/${locale}/${key}.json`,  }),];

Siehe auch: docs/de/intlayer_with_next-intl.md.

react-intl

Einzelne JSON-Datei pro Locale ist üblich:

plugins: [  syncJSON({    source: ({ locale }) => `./locales/${locale}.json`,  }),];

vue-i18n

Entweder eine einzelne Datei pro Locale oder pro Namespace:

plugins: [  syncJSON({    source: ({ key, locale }) => `./src/locales/${locale}/${key}.json`,  }),];

CLI

Die synchronisierten JSON-Dateien werden wie andere .content-Dateien behandelt. Das bedeutet, dass alle intlayer-Befehle für die synchronisierten JSON-Dateien verfügbar sind. Einschließlich:

• intlayer content test, um zu testen, ob Übersetzungen fehlen
• intlayer content list, um die synchronisierten JSON-Dateien aufzulisten
• intlayer content fill, um fehlende Übersetzungen zu ergänzen
• intlayer content push, um die synchronisierten JSON-Dateien zu pushen
• intlayer content pull, um die synchronisierten JSON-Dateien zu pullen

Siehe Intlayer CLI für weitere Details.

Einschränkungen (aktuell)

• Keine Unterstützung für Einfügungen oder Pluralformen/ICU bei der Verwendung von Drittanbieter-Bibliotheken.
• Visueller Editor ist für Nicht-Intlayer-Laufzeiten noch nicht verfügbar.
• Nur JSON-Synchronisierung; Nicht-JSON-Katalogformate werden nicht unterstützt.

Warum das wichtig ist

• Wir können etablierte i18n-Lösungen empfehlen und Intlayer als Zusatzmodul positionieren.
• Wir nutzen deren SEO/Schlüsselwörter mit Tutorials, die abschließend vorschlagen, Intlayer zur Verwaltung von JSON einzusetzen.
• Erweitert die ansprechbare Zielgruppe von „neuen Projekten“ auf „jedes Team, das bereits i18n verwendet“.