Intlayer Compiler | Automatisierte Inhaltsextraktion für i18n

Was ist der Intlayer Compiler?

Der Intlayer Compiler ist ein leistungsstarkes Werkzeug, das entwickelt wurde, um den Prozess der Internationalisierung (i18n) in Ihren Anwendungen zu automatisieren. Er durchsucht Ihren Quellcode (JSX, TSX, Vue, Svelte) nach Inhaltsdeklarationen, extrahiert diese und generiert automatisch die notwendigen Wörterbuchdateien. Dadurch können Sie Ihre Inhalte direkt bei den Komponenten belassen, während Intlayer die Verwaltung und Synchronisierung Ihrer Wörterbücher übernimmt.

Warum den Intlayer Compiler verwenden?

• Automatisierung: Beseitigt das manuelle Kopieren und Einfügen von Inhalten in Wörterbücher.
• Geschwindigkeit: Optimierte Inhaltsextraktion, die sicherstellt, dass Ihr Build-Prozess schnell bleibt.
• Entwicklererfahrung: Behalten Sie Inhaltsdeklarationen genau dort, wo sie verwendet werden, und verbessern Sie so die Wartbarkeit.
• Live-Updates: Unterstützt Hot Module Replacement (HMR) für sofortiges Feedback während der Entwicklung.

Siehe den Blogbeitrag Compiler vs. Declarative i18n für einen tieferen Vergleich.

Warum den Intlayer Compiler nicht verwenden?

Während der Compiler eine ausgezeichnete "funktioniert einfach so"-Erfahrung bietet, führt er auch einige Kompromisse ein, die Sie beachten sollten:

• Heuristische Mehrdeutigkeit: Der Compiler muss erraten, was benutzerorientierter Inhalt im Gegensatz zur Anwendungslogik ist (z. B. className="active", Statuscodes, Produkt-IDs). In komplexen Codebasen kann dies zu falschen Positiven oder übersehenen Zeichenketten führen, die manuelle Anmerkungen und Ausnahmen erfordern.
• Nur statische Extraktion: Die compilerbasierte Extraktion basiert auf statischer Analyse. Zeichenketten, die nur zur Laufzeit existieren (API-Fehlercodes, CMS-Felder usw.), können vom Compiler allein nicht entdeckt oder übersetzt werden, daher benötigen Sie immer noch eine ergänzende Laufzeit-i18n-Strategie.

Für einen tieferen architektonischen Vergleich siehe den Blogbeitrag Compiler vs. Declarative i18n.

Als Alternative, um Ihren i18n-Prozess zu automatisieren und gleichzeitig die volle Kontrolle über Ihren Inhalt zu behalten, bietet Intlayer auch einen Auto-Extraktionsbefehl intlayer extract (siehe CLI-Dokumentation) oder den Befehl Intlayer: extract content to Dictionary aus der Intlayer VS Code-Erweiterung (siehe VS Code-Erweiterungsdokumentation).

Verwendung

npm install vite-intlayer

import { defineConfig } from "vite";import { intlayer, intlayerCompiler } from "vite-intlayer";export default defineConfig({ plugins: [   intlayer(),   intlayerCompiler(), // Fügt das Compiler-Plugin hinzu ],});

# Für Vuenpm install @intlayer/vue-compiler# Für Sveltenpm install @intlayer/svelte-compiler

npm install @intlayer/babel

const { intlayerExtractBabelPlugin, intlayerOptimizeBabelPlugin, getExtractPluginOptions, getOptimizePluginOptions,} = require("@intlayer/babel");module.exports = { presets: ["next/babel"], plugins: [   // Extract content from components into dictionaries   [intlayerExtractBabelPlugin, getExtractPluginOptions()],   // Optimize imports by replacing useIntlayer with direct dictionary imports   [intlayerOptimizeBabelPlugin, getOptimizePluginOptions()], ],};

Benutzerdefinierte Konfiguration

Um das Verhalten des Compilers anzupassen, können Sie die Datei intlayer.config.ts im Stammverzeichnis Ihres Projekts aktualisieren.

import { type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  compiler: {    /**     * Gibt an, ob der Compiler aktiviert werden soll.     * Stellen Sie build-only ein, um den Compiler während der Entwicklung zu überspringen und die Startzeiten zu beschleunigen.     */    enabled: true,    /**     * Definiert den Pfad der Ausgabedateien. Ersetzt `outputDir`.     *     * - `./` Pfade werden relativ zum Verzeichnis der Komponente aufgelöst.     * - `/` Pfade werden relativ zum Projektstamm (`baseDir`) aufgelöst.     *     * - Das Einbeziehen der Variable `{{locale}}` im Pfad löst die Generierung separater Wörterbücher pro Sprache aus.     *     * Beispiel:     * ```ts     * {     *   // Erstelle mehrsprachige .content.ts-Dateien in der Nähe der Komponente     *   output: ({ fileName, extension }) => `./${fileName}${extension}`,     *     *   // output: './{{fileName}}{{extension}}', // Äquivalent mit einem Template-String     * }     * ```     *     * ```ts     * {     *   // Erstelle zentralisierte JSON-Dateien pro Sprache im Projektstamm     *   output: ({ key, locale }) => `/locales/${locale}/${key}.content.json`,     *     *   // output: '/locales/{{locale}}/{{key}}.content.json', // Äquivalent mit einem Template-String     * }     * ```     *     * Liste der Variablen:     *   - `fileName`: Der Name der Datei.     *   - `key`: Der Schlüssel des Inhalts.     *   - `locale`: Die Sprache des Inhalts.     *   - `extension`: Die Dateierweiterung.     *   - `componentFileName`: Der Dateiname der Komponente.     *   - `componentExtension`: Die Dateierweiterung der Komponente.     *   - `format`: Das Wörterbuchformat.     *   - `componentFormat`: Das Wörterbuchformat der Komponente.     *   - `componentDirPath`: Der Verzeichnispfad der Komponente.     */    output: ({ fileName, extension }) => `./${fileName}${extension}`,    /**     * Gibt an, ob die Komponenten nach der Transformation gespeichert werden sollen.     *     * - Wenn `true`, schreibt der Compiler die Komponentendatei auf die Festplatte um. Die Transformation ist also dauerhaft und der Compiler überspringt die Transformation für den nächsten Prozess. Auf diese Weise kann der Compiler die App transformieren und anschließend entfernt werden.     *     * - Wenn `false`, fügt der Compiler den `useIntlayer()` Funktionsaufruf nur in den Code der Build-Ausgabe ein und lässt die Basis-Code-Basis intakt. Die Transformation erfolgt nur im Speicher.     */    saveComponents: false,    /**     * Fügt nur den Inhalt in die generierte Datei ein. Hilfreich für i18next oder ICU MessageFormat pro Sprach-JSON-Ausgaben.     *     * - `output: ({ locale, key }) => `./locale/${locale}/${key}.json`,`     */    noMetadata: false,    /**     * Wörterbuch-Schlüssel-Präfix     */    dictionaryKeyPrefix: "", // Optionales Präfix für extrahierte Wörterbuchschlüssel hinzufügen  },};export default config;

Compiler-Konfigurationsreferenz

Die folgenden Eigenschaften können im Block compiler Ihrer Datei intlayer.config.ts konfiguriert werden:

• enabled:

  • Typ: boolean | 'build-only'
  • Standard: true
  • Beschreibung: Gibt an, ob der Compiler aktiviert werden soll.

• dictionaryKeyPrefix:

  • Typ: string
  • Standard: ''
  • Beschreibung: Präfix für die extrahierten Wörterbuchschlüssel.

• transformPattern:

  • Typ: string | string[]
  • Standard: ['**/*.{js,ts,mjs,cjs,jsx,tsx,vue,svelte}', '!**/node_modules/**']
  • Beschreibung: (Veraltet: verwenden Sie stattdessen build.traversePattern) Muster zum Durchlaufen des zu optimierenden Codes.

• excludePattern:

  • Typ: string | string[]
  • Standard: ['**/node_modules/**']
  • Beschreibung: (Veraltet: verwenden Sie stattdessen build.traversePattern) Muster, die von der Optimierung ausgeschlossen werden sollen.

• output:

  • Typ: FilePathPattern
  • Standard: ({ key }) => 'compiler/${key}.content.json'
  • Beschreibung: Definiert den Pfad der Ausgabedateien. Ersetzt outputDir. Verarbeitet dynamische Variablen wie {{locale}}, {{key}}, {{fileName}}, {{extension}}, {{format}}, {{dirPath}}, {{componentFileName}}, {{componentExtension}}, {{componentFormat}}. Kann als String im Format 'my/{{var}}/path' oder als Funktion festgelegt werden.
  • Hinweis: ./**/* Pfade werden relativ zur Komponente aufgelöst. /**/* Pfade werden relativ zum Intlayer baseDir aufgelöst.
  • Hinweis: Wenn die Locale im Pfad gesetzt ist, werden Wörterbücher pro Locale generiert.
  • Beispiel: output: ({ locale, key }) => 'compiler/${locale}/${key}.json'

• noMetadata:

  • Typ: boolean
  • Standard: false
  • Beschreibung: Gibt an, ob die Metadaten in der Datei gespeichert werden sollen. Wenn true, speichert der Compiler nicht die Metadaten der Wörterbücher (Schlüssel, Content-Wrapper). Nützlich für i18next- oder ICU-MessageFormat-JSON-Ausgaben pro Sprache.
  • Hinweis: Nützlich bei Verwendung mit dem loadJSON-Plugin.
  • Beispiel: Wenn true: json { "key": "value" } Wenn false: json { "key": "value", "content": { "key": "value" } }

• saveComponents:

  • Typ: boolean
  • Standard: false
  • Beschreibung: Gibt an, ob die Komponenten nach der Transformation gespeichert werden sollen.
    • Wenn true, schreibt der Compiler die Komponentendatei auf die Festplatte um. Die Transformation ist dauerhaft und der Compiler kann anschließend entfernt werden.
    • Wenn false, fügt der Compiler den useIntlayer() Funktionsaufruf nur in den Code der Build-Ausgabe ein und lässt die Basis-Code-Basis intakt. Die Transformation erfolgt nur im Speicher.

Fehlende Übersetzungen ausfüllen

Intlayer bietet ein CLI-Tool an, mit dem Sie fehlende Übersetzungen ausfüllen können. Sie können den Befehl intlayer verwenden, um fehlende Übersetzungen in Ihrem Code zu testen und auszufüllen.

npx intlayer test         # Testen, ob Übersetzungen fehlen

npx intlayer fill         # Fehlende Übersetzungen ausfüllen

Extraktion

Intlayer bietet ein CLI-Tool, um Inhalte aus Ihrem Code zu extrahieren. Sie können den Befehl intlayer extract verwenden, um Inhalte aus Ihrem Code zu extrahieren.

npx intlayer extract

Weitere Informationen finden Sie in der CLI-Dokumentation