Intlayer Compiler | Extraction Automatisée de Contenu pour i18n

Qu'est-ce que l'Intlayer Compiler ?

Le Intlayer Compiler est un outil puissant conçu pour automatiser le processus d'internationalisation (i18n) dans vos applications. Il analyse votre code source (JSX, TSX, Vue, Svelte) à la recherche de déclarations de contenu, les extrait, et génère automatiquement les fichiers de dictionnaire nécessaires. Cela vous permet de garder votre contenu localisé avec vos composants tandis qu'Intlayer gère la gestion et la synchronisation de vos dictionnaires.

Pourquoi utiliser le Intlayer Compiler ?

• Automatisation : Élimine le copier-coller manuel du contenu dans les dictionnaires.
• Rapidité : Extraction de contenu optimisée garantissant que votre processus de build reste rapide.
• Expérience développeur : Gardez les déclarations de contenu là où elles sont utilisées, améliorant ainsi la maintenabilité.
• Mises à jour en direct : Prend en charge le Hot Module Replacement (HMR) pour un retour instantané pendant le développement.

Consultez l'article de blog Compiler vs. Declarative i18n pour une comparaison plus approfondie.

Pourquoi ne pas utiliser l'Intlayer Compiler ?

Bien que le compilateur offre une excellente expérience "fonctionne tout seul", il introduit également certains compromis dont vous devez être conscient :

• Ambiguïté heuristique : Le compilateur doit deviner ce qui est du contenu destiné aux utilisateurs par rapport à la logique de l'application (par exemple, className="active", codes de statut, identifiants de produits). Dans des bases de code complexes, cela peut conduire à de faux positifs ou à des chaînes manquées qui nécessitent des annotations manuelles et des exceptions.
• Extraction statique uniquement : L'extraction basée sur le compilateur repose sur l'analyse statique. Les chaînes qui n'existent qu'à l'exécution (codes d'erreur API, champs CMS, etc.) ne peuvent pas être découvertes ou traduites par le compilateur seul, vous avez donc toujours besoin d'une stratégie i18n d'exécution complémentaire.

Pour une comparaison architecturale plus approfondie, consultez l'article de blog Compiler vs. Declarative i18n.

Comme alternative, pour automatiser votre processus i18n tout en gardant un contrôle total de votre contenu, Intlayer fournit également une commande d'auto-extraction intlayer extract (voir la documentation CLI), ou la commande Intlayer: extract content to Dictionary de l'extension Intlayer VS Code (voir la documentation de l'extension VS Code).

Utilisation

npm install vite-intlayer

import { defineConfig } from "vite";import { intlayer, intlayerCompiler } from "vite-intlayer";export default defineConfig({ plugins: [   intlayer(),   intlayerCompiler(), // Ajoute le plugin du compilateur ],});

# Pour Vuenpm install @intlayer/vue-compiler# Pour 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()], ],};

Configuration personnalisée

Pour personnaliser le comportement du compilateur, vous pouvez mettre à jour le fichier intlayer.config.ts à la racine de votre projet.

import { type IntlayerConfig, Locales } from "intlayer";const config: IntlayerConfig = {  compiler: {    /**     * Indique si le compilateur doit être activé.     * Réglez sur 'build-only' pour ignorer le compilateur pendant le développement et accélérer les temps de démarrage.     */    enabled: true,    /**     * Définit le chemin des fichiers de sortie. Remplace `outputDir`.     *     * - Les chemins `./` sont résolus par rapport au répertoire du composant.     * - Les chemins `/` sont résolus par rapport à la racine du projet (`baseDir`).     *     * - L'inclusion de la variable `{{locale}}` dans le chemin déclenchera la génération de dictionnaires séparés par locale.     *     * Exemple :     * ```ts     * {     *   // Créer des fichiers .content.ts multilingues proches du composant     *   output: ({ fileName, extension }) => `./${fileName}${extension}`,     *     *   // output: './{{fileName}}{{extension}}', // Équivalent utilisant une chaîne de caractères     * }     * ```     *     * ```ts     * {     *   // Créer des JSON centralisés par locale à la racine du projet     *   output: ({ key, locale }) => `/locales/${locale}/${key}.content.json`,     *     *   // output: '/locales/{{locale}}/{{key}}.content.json', // Équivalent utilisant une chaîne de caractères     * }     * ```     *     * Liste des variables :     *   - `fileName`: Le nom du fichier.     *   - `key`: La clé du contenu.     *   - `locale`: La locale du contenu.     *   - `extension`: L'extension du fichier.     *   - `componentFileName`: Le nom du fichier du composant.     *   - `componentExtension`: L'extension du fichier du composant.     *   - `format`: Le format du dictionnaire.     *   - `componentFormat`: Le format du dictionnaire du composant.     *   - `componentDirPath`: Le chemin du répertoire du composant.     */    output: ({ fileName, extension }) => `./${fileName}${extension}`,    /**     * Indique si les composants doivent être enregistrés après avoir été transformés.     *     * - Si `true`, le compilateur réécrira le fichier du composant sur le disque. Ainsi, la transformation sera permanente et le compilateur sautera la transformation pour le prochain processus. De cette façon, le compilateur peut transformer l'application, puis être supprimé.     *     * - Si `false`, le compilateur injectera l'appel de fonction `useIntlayer()` dans le code du build uniquement et gardera la base de code intacte. La transformation sera effectuée uniquement en mémoire.     */    saveComponents: false,    /**     * Insérer uniquement le contenu dans le fichier généré. Utile pour les sorties JSON i18next ou ICU MessageFormat par locale.     *     * - `output: ({ locale, key }) => `./locale/${locale}/${key}.json`,`     */    noMetadata: false,    /**     * Préfixe de clé de dictionnaire     */    dictionaryKeyPrefix: "", // Ajouter un préfixe optionnel pour les clés de dictionnaire extraites  },};export default config;

Référence de la configuration du compilateur

Les propriétés suivantes peuvent être configurées dans le bloc compiler de votre fichier intlayer.config.ts :

• enabled:

  • Type: boolean | 'build-only'
  • Par défaut: true
  • Description: Indique si le compilateur doit être activé.

• dictionaryKeyPrefix:

  • Type: string
  • Par défaut: ''
  • Description: Préfixe pour les clés de dictionnaire extraites.

• transformPattern:

  • Type: string | string[]
  • Par défaut: ['**/*.{js,ts,mjs,cjs,jsx,tsx,vue,svelte}', '!**/node_modules/**']
  • Description: (Obsolète : utilisez build.traversePattern à la place) Modèles pour parcourir le code à optimiser.

• excludePattern:

  • Type: string | string[]
  • Par défaut: ['**/node_modules/**']
  • Description: (Obsolète : utilisez build.traversePattern à la place) Modèles à exclure de l'optimisation.

• output:

  • Type: FilePathPattern
  • Par défaut: ({ key }) => 'compiler/${key}.content.json'
  • Description: Définit le chemin des fichiers de sortie. Remplace outputDir. Gère les variables dynamiques telles que {{locale}}, {{key}}, {{fileName}}, {{extension}}, {{format}}, {{dirPath}}, {{componentFileName}}, {{componentExtension}}, {{componentFormat}}. Peut être configuré sous forme de chaîne à l'aide du format 'my/{{var}}/path' ou sous forme de fonction.
  • Note: ./**/* Les chemins sont résolus par rapport au composant. /**/* les chemins sont résolus par rapport au baseDir d'Intlayer.
  • Note: Si la locale est définie dans le chemin, cela générera des dictionnaires par locale.
  • Exemple: output: ({ locale, key }) => 'compiler/${locale}/${key}.json'

• noMetadata:

  • Type: boolean
  • Par défaut: false
  • Description: Indique si les métadonnées doivent être enregistrées dans le fichier. Si vrai, le compilateur n'enregistrera pas les métadonnées des dictionnaires (clé, enveloppe de contenu). Utile pour les sorties JSON i18next ou ICU MessageFormat par locale.
  • Note: Utile si utilisé avec le plugin loadJSON.
  • Exemple: Si true : json { "key": "value" } Si false : json { "key": "value", "content": { "key": "value" } }

• saveComponents:

  • Type: boolean
  • Par défaut: false
  • Description: Indique si les composants doivent être enregistrés après avoir été transformés.
    • Si true, le compilateur réécrira le fichier du composant sur le disque. La transformation sera permanente et le compilateur pourra ensuite être supprimé.
    • Si false, le compilateur injectera l'appel de fonction useIntlayer() dans le code du build uniquement et gardera la base de code intacte. La transformation sera effectuée uniquement en mémoire.

Remplir les traductions manquantes

Intlayer fournit un outil CLI pour vous aider à remplir les traductions manquantes. Vous pouvez utiliser la commande intlayer pour tester et remplir les traductions manquantes à partir de votre code.

npx intlayer test         # Tester s'il y a des traductions manquantes

npx intlayer fill         # Remplir les traductions manquantes

Extraction

Intlayer propose un outil CLI pour extraire le contenu de votre code. Vous pouvez utiliser la commande intlayer extract pour extraire le contenu de votre code.

npx intlayer extract

Pour plus de détails, consultez la documentation CLI