Documentation de Configuration d'Intlayer

Vue d'ensemble

Les fichiers de configuration d'Intlayer permettent de personnaliser divers aspects du plugin, tels que l'internationalisation, le middleware et la gestion du contenu. Ce document fournit une description détaillée de chaque propriété de la configuration.

Formats de fichiers de configuration supportés

Intlayer accepte les formats de fichiers de configuration JSON, JS, MJS et TS :

• intlayer.config.ts
• intlayer.config.js
• intlayer.config.json
• intlayer.config.cjs
• intlayer.config.mjs
• .intlayerrc

Exemple de fichier de configuration

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH], // liste des locales supportées  },  content: {    autoFill: "./{{fileName}}.content.json", // remplissage automatique du contenu    contentDir: ["src", "../ui-library"], // répertoires de contenu  },  middleware: {    noPrefix: false, // utilisation du préfixe dans le middleware  },  editor: {    applicationURL: "https://example.com", // URL de l'application pour l'éditeur  },  ai: {    apiKey: process.env.OPENAI_API_KEY, // clé API pour l'IA    applicationContext: "This is a test application", // contexte de l'application pour l'IA  },  build: {    importMode: "dynamic", // mode d'importation pour la construction  },};export default config;

Référence de configuration

Les sections suivantes décrivent les différents paramètres de configuration disponibles pour Intlayer.

Configuration de l'internationalisation

Définit les paramètres liés à l'internationalisation, y compris les locales disponibles et la locale par défaut de l'application.

Propriétés

• locales :

  • Type : string[]
  • Par défaut : ['en']
  • Description : La liste des locales supportées dans l'application.
  • Exemple : ['en', 'fr', 'es']
• requiredLocales :
  • Type : string[]
  • Par défaut : []
  • Description : La liste des locales requises dans l'application.
  • Exemple : []
  • Note : Si vide, toutes les locales sont requises en mode strict.
  • Note : Assurez-vous que les locales requises sont également définies dans le champ locales.

• strictMode :

  • Type : string
  • Défaut : inclusive
  • Description : Assure une implémentation stricte du contenu internationalisé en utilisant TypeScript.
  • Note : Si défini sur "strict", la fonction de traduction t exigera que chaque locale déclarée soit définie. Si une locale est manquante, ou si une locale n'est pas déclarée dans votre configuration, cela générera une erreur.
  • Note : Si défini sur "inclusive", la fonction de traduction t exigera que chaque locale déclarée soit définie. Si une locale est manquante, cela générera un avertissement. Mais acceptera si une locale n'est pas déclarée dans votre configuration, mais existe.
  • Note : Si défini sur "loose", la fonction de traduction t acceptera n'importe quelle locale existante.

• defaultLocale :

  • Type : string
  • Défaut : 'en'
  • Description : La locale par défaut utilisée comme solution de repli si la locale demandée n'est pas trouvée.
  • Exemple : 'en'
  • Note : Ceci est utilisé pour déterminer la locale lorsqu'aucune n'est spécifiée dans l'URL, le cookie ou l'en-tête.

Configuration de l'éditeur

Définit les paramètres liés à l'éditeur intégré, y compris le port du serveur et le statut actif.

Propriétés

• applicationURL :

  • Type : string
  • Défaut : http://localhost:3000
  • Description : L'URL de l'application. Utilisée pour restreindre l'origine de l'éditeur pour des raisons de sécurité.
  • Exemple :
    • 'http://localhost:3000'
    • 'https://example.com'
    • process.env.INTLAYER_EDITOR_URL
  • Note : L'URL de l'application. Utilisée pour restreindre l'origine de l'éditeur pour des raisons de sécurité. Si elle est définie sur '*', l'éditeur est accessible depuis n'importe quelle origine.

• port :

  • Type : number
  • Défaut : 8000
  • Description : Le port utilisé par le serveur de l'éditeur visuel.

• editorURL :

  • Type : string
  • Défaut : 'http://localhost:8000'
  • Description : L'URL du serveur de l'éditeur. Utilisée pour restreindre l'origine de l'éditeur pour des raisons de sécurité.
    • 'http://localhost:3000'
    • 'https://example.com'
    • process.env.INTLAYER_EDITOR_URL
  • Note : L’URL du serveur de l’éditeur à atteindre depuis l’application. Utilisée pour restreindre les origines pouvant interagir avec l’application pour des raisons de sécurité. Si définie à '*', l’éditeur est accessible depuis n’importe quelle origine. Doit être définie si le port est modifié, ou si l’éditeur est hébergé sur un domaine différent.

• cmsURL :

  • Type : string
  • Défaut : 'https://intlayer.org'
  • Description : L’URL du CMS Intlayer.
  • Exemple : 'https://intlayer.org'
  • Note : L’URL du CMS Intlayer.

• backendURL :

  • Type : string
  • Défaut : https://back.intlayer.org
  • Description : L’URL du serveur backend.
  • Exemple : http://localhost:4000

• enabled :

  • Type : boolean
  • Défaut : true
  • Description : Indique si l'application interagit avec l'éditeur visuel.
  • Exemple : process.env.NODE_ENV !== 'production'
  • Note : Si vrai, l'éditeur pourra interagir avec l'application. Si faux, l'éditeur ne pourra pas interagir avec l'application. Dans tous les cas, l'éditeur ne peut être activé que par l'éditeur visuel. Désactiver l'éditeur pour des environnements spécifiques est une manière de renforcer la sécurité.

• clientId :

  • Type : string | undefined
  • Par défaut : undefined
  • Description : clientId et clientSecret permettent aux packages intlayer de s'authentifier auprès du backend en utilisant l'authentification oAuth2. Un jeton d'accès est utilisé pour authentifier l'utilisateur lié au projet. Pour obtenir un jeton d'accès, rendez-vous sur https://intlayer.org/dashboard/project et créez un compte.
  • Exemple : true
  • Note : Important : Le clientId et le clientSecret doivent rester secrets et ne pas être partagés publiquement. Veuillez vous assurer de les conserver dans un endroit sécurisé, comme des variables d'environnement.

• clientSecret :

  • Type : string | undefined
  • Défaut : undefined
  • Description : clientId et clientSecret permettent aux packages intlayer de s'authentifier auprès du backend en utilisant l'authentification oAuth2. Un jeton d'accès est utilisé pour authentifier l'utilisateur lié au projet. Pour obtenir un jeton d'accès, rendez-vous sur https://intlayer.org/dashboard/project et créez un compte.
  • Exemple : true
  • Note : Important : Le clientId et le clientSecret doivent rester secrets et ne pas être partagés publiquement. Veuillez vous assurer de les conserver dans un endroit sécurisé, comme des variables d'environnement.

• dictionaryPriorityStrategy :

  • Type : string
  • Défaut : 'local_first'
  • Description : La stratégie pour prioriser les dictionnaires dans le cas où des dictionnaires locaux et distants sont présents. Si défini sur 'distant_first', l'application priorisera les dictionnaires distants par rapport aux dictionnaires locaux. Si défini sur 'local_first', l'application priorisera les dictionnaires locaux par rapport aux dictionnaires distants.
  • Exemple : 'distant_first'

• liveSync :

  • Type : boolean
  • Par défaut : false
  • Description : Indique si le serveur de l'application doit recharger à chaud le contenu de l'application lorsqu'un changement est détecté sur le CMS / Éditeur Visuel / Backend.
  • Exemple : true
  • Note : Par exemple, lorsqu'un nouveau dictionnaire est ajouté ou mis à jour, l'application mettra à jour le contenu à afficher dans la page.
  • Note : La synchronisation en direct nécessite d'externaliser le contenu de l'application vers un autre serveur. Cela signifie que cela peut légèrement impacter les performances de l'application. Pour limiter cela, nous recommandons d'héberger l'application et le serveur de synchronisation en direct sur la même machine. De plus, la combinaison de la synchronisation en direct et de optimize peut générer un nombre conséquent de requêtes vers le serveur de synchronisation en direct. En fonction de votre infrastructure, nous recommandons de tester les deux options ainsi que leur combinaison.

• liveSyncPort :

  • Type : number
  • Par défaut : 4000
  • Description : Le port du serveur de synchronisation en direct.
  • Exemple : 4000
  • Note : Le port du serveur de synchronisation en direct.

• liveSyncURL :

  • Type : string
  • Par défaut : 'http://localhost:{liveSyncPort}'
  • Description : L'URL du serveur de synchronisation en direct.
  • Exemple : 'https://example.com'
  • Note : Pointe vers localhost par défaut mais peut être modifiée vers n'importe quelle URL dans le cas d'un serveur de synchronisation en direct distant.

Configuration du Middleware

Paramètres qui contrôlent le comportement du middleware, y compris la gestion des cookies, des en-têtes et des préfixes d'URL pour la gestion des locales.

Propriétés

• headerName :

  • Type : string
  • Par défaut : 'x-intlayer-locale'
  • Description : Le nom de l'en-tête HTTP utilisé pour déterminer la locale.
  • Exemple : 'x-custom-locale'
  • Note : Utile pour la détermination de la locale basée sur une API.

• cookieName :

  • Type : string
  • Par défaut : 'intlayer-locale'
  • Description : Le nom du cookie utilisé pour stocker la locale.
  • Exemple : 'custom-locale'
  • Note : Utilisé pour conserver la locale entre les sessions.

• prefixDefault :

  • Type : boolean
  • Par défaut : false
  • Description : Indique s'il faut inclure la locale par défaut dans l'URL.
  • Exemple : true
  • Note :
    • Si true et defaultLocale = 'en' : chemin = /en/dashboard ou /fr/dashboard
    • Si false et defaultLocale = 'en' : chemin = /dashboard ou /fr/dashboard

• basePath :

  • Type : string
  • Par défaut : ''
  • Description : Le chemin de base pour les URLs de l'application.
  • Exemple : '/my-app'
  • Note :
    • Si l'application est hébergée à https://example.com/my-app
    • Le chemin de base est '/my-app'
    • L'URL sera https://example.com/my-app/en
    • Si le chemin de base n'est pas défini, l'URL sera https://example.com/en

• serverSetCookie :

  • Type : string
  • Par défaut : 'always'
  • Description : Règle pour définir le cookie de langue sur le serveur.
  • Options : 'always', 'never'
  • Exemple : 'never'
  • Note : Contrôle si le cookie de langue est défini à chaque requête ou jamais.

• noPrefix :

  • Type : boolean
  • Par défaut : false
  • Description : Indique s'il faut omettre le préfixe de langue dans les URLs.
  • Exemple : true
  • Note :
    • Si true : Pas de préfixe dans l'URL
    • Si false : Préfixe dans l'URL
    • Exemple avec basePath = '/my-app' :
      • Si noPrefix = false : l'URL sera https://example.com/my-app/en
      • Si noPrefix = true : l'URL sera https://example.com

• detectLocaleOnPrefetchNoPrefix :

  • Type : boolean
  • Par défaut : false
  • Description : Contrôle si la détection de la locale se produit lors des requêtes de préchargement (prefetch) de Next.js.
  • Exemple : true
  • Note : Ce paramètre influence la manière dont Next.js gère le préchargement des locales :
    • Scénario d'exemple :
      • La langue du navigateur de l'utilisateur est 'fr'
      • La page actuelle est /fr/about
      • Un lien précharge /about
    • Avec detectLocaleOnPrefetchNoPrefix: true :
      • Le préchargement détecte la locale 'fr' depuis le navigateur
      • Redirige le préchargement vers /fr/about
    • Avec detectLocaleOnPrefetchNoPrefix: false (par défaut) :
      • Le préchargement utilise la locale par défaut
      • Redirige le préchargement vers /en/about (en supposant que 'en' est la locale par défaut)
    • Quand utiliser true :
      • Votre application utilise des liens internes non localisés (par exemple <a href="/about">)
      • Vous souhaitez un comportement cohérent de détection de la langue entre les requêtes normales et les requêtes de préchargement
    • Quand utiliser false (par défaut) :
      • Votre application utilise des liens préfixés par la langue (par exemple <a href="/fr/about">)
      • Vous souhaitez optimiser les performances du préchargement
      • Vous souhaitez éviter les boucles de redirection potentielles

Configuration du contenu

Paramètres liés à la gestion du contenu au sein de l'application, incluant les noms de répertoires, les extensions de fichiers et les configurations dérivées.

Propriétés

• autoFill :

  • Type : boolean | string | { [key in Locales]?: string }
  • Défaut : undefined
  • Description : Indique comment le contenu doit être automatiquement rempli à l'aide de l'IA. Peut être déclaré globalement dans le fichier intlayer.config.ts.
  • Exemple : true
  • Exemple : './{{fileName}}.content.json'
  • Exemple : { fr: './{{fileName}}.fr.content.json', es: './{{fileName}}.es.content.json' }
  • Note : La configuration de remplissage automatique. Elle peut être :
    • boolean : Activer le remplissage automatique pour toutes les locales
    • string : Chemin vers un fichier unique ou un modèle avec variables
    • object : Chemins de fichiers par locale

• watch :

  • Type : boolean
  • Défaut : process.env.NODE_ENV === 'development'
  • Description : Indique si Intlayer doit surveiller les modifications dans les fichiers de déclaration de contenu de l'application pour reconstruire les dictionnaires associés.

• fileExtensions :

  • Type : string[]
  • Défaut : ['.content.ts', '.content.js', '.content.cjs', '.content.mjs', '.content.json', '.content.tsx', '.content.jsx']
  • Description : Extensions de fichiers à rechercher lors de la construction des dictionnaires.
  • Exemple : ['.data.ts', '.data.js', '.data.json']
  • Note : Personnaliser les extensions de fichiers peut aider à éviter les conflits.

• baseDir :

  • Type : string
  • Défaut : process.cwd()
  • Description : Le répertoire de base pour le projet.
  • Exemple : '/path/to/project'
  • Note : Ceci est utilisé pour résoudre tous les répertoires liés à Intlayer.

• dictionaryOutput :

  • Type : string[]
  • Défaut : ['intlayer']
  • Description : Le type de sortie de dictionnaire à utiliser, par exemple 'intlayer' ou 'i18next'.

• contentDir :

  • Type : string[]
  • Défaut : ['.']
  • Exemple : ['src', '../../ui-library', require.resolve("@my-package/content")]
  • Description : Le chemin du répertoire où le contenu est stocké.

• dictionariesDir :

  • Type : string
  • Par défaut : '.intlayer/dictionaries'
  • Description : Le chemin du répertoire pour stocker les résultats intermédiaires ou finaux.

• moduleAugmentationDir :

  • Type : string
  • Par défaut : '.intlayer/types'
  • Description : Répertoire pour l'augmentation de module, permettant de meilleures suggestions IDE et vérifications de types.
  • Exemple : 'intlayer-types'
  • Note : Veillez à inclure ce répertoire dans tsconfig.json.

• unmergedDictionariesDir :

  • Type : string
  • Par défaut : '.intlayer/unmerged_dictionary'
  • Description : Le répertoire pour stocker les dictionnaires non fusionnés.
  • Exemple : 'translations'

• dictionariesDir :

  • Type : string
  • Par défaut : '.intlayer/dictionary'
  • Description : Le répertoire pour stocker les dictionnaires de localisation.
  • Exemple : 'translations'

• i18nextResourcesDir :

  • Type : string
  • Par défaut : 'i18next_dictionary'
  • Description : Le répertoire pour stocker les dictionnaires i18n.
  • Exemple : 'translations'
  • Note : Assurez-vous que ce répertoire est configuré pour le type de sortie i18next.

• typesDir :

  • Type : string
  • Par défaut : 'types'
  • Description : Le répertoire pour stocker les types de dictionnaires.
  • Exemple : 'intlayer-types'

• mainDir :

  • Type : string
  • Par défaut : 'main'
  • Description : Le répertoire où sont stockés les fichiers principaux de l'application.
  • Exemple : 'intlayer-main'

• excludedPath :

  • Type: string[]
  • Default: ['node_modules']
  • Description: Répertoires exclus de la recherche de contenu.
  • Note: Ce paramètre n'est pas encore utilisé, mais est prévu pour une future mise en œuvre.

Configuration du Logger

Paramètres qui contrôlent le logger, y compris le préfixe à utiliser.

Propriétés

• mode :

  • Type : string
  • Default : default
  • Description : Indique le mode du logger.
  • Options : default, verbose, disabled
  • Example : default
  • Note : Le mode du logger. Le mode verbose enregistrera plus d'informations, mais peut être utilisé à des fins de débogage. Le mode disabled désactivera le logger.

• prefix :

  • Type : string
  • Default : '[intlayer] '
  • Description : Le préfixe du logger.
  • Example : '[my custom prefix] '
  • Note: Le préfixe du logger.

Configuration de l'IA

Paramètres qui contrôlent les fonctionnalités d'IA d'Intlayer, y compris le fournisseur, le modèle et la clé API.

Cette configuration est optionnelle si vous êtes inscrit sur le Tableau de bord Intlayer en utilisant une clé d'accès. Intlayer gérera automatiquement la solution d'IA la plus efficace et la plus rentable pour vos besoins. Utiliser les options par défaut garantit une meilleure maintenabilité à long terme, car Intlayer met continuellement à jour pour utiliser les modèles les plus pertinents.

Si vous préférez utiliser votre propre clé API ou un modèle spécifique, vous pouvez définir votre configuration IA personnalisée. Cette configuration IA sera utilisée globalement dans votre environnement Intlayer. Les commandes CLI utiliseront ces paramètres par défaut pour les commandes (par exemple fill), ainsi que le SDK, l'éditeur visuel et le CMS. Vous pouvez remplacer ces valeurs par défaut pour des cas d'utilisation spécifiques en utilisant des paramètres de commande.

Intlayer prend en charge plusieurs fournisseurs d'IA pour une flexibilité et un choix accrus. Les fournisseurs actuellement pris en charge sont :

• OpenAI (par défaut)
• Anthropic Claude
• Mistral AI
• DeepSeek
• Google Gemini
• Meta Llama

Propriétés

• provider :

  • Type : string
  • Par défaut : 'openai'
  • Description : Le fournisseur à utiliser pour les fonctionnalités IA d'Intlayer.
  • Options : 'openai', 'anthropic', 'mistral', 'deepseek', 'gemini'
  • Exemple : 'anthropic'
  • Note: Différents fournisseurs peuvent nécessiter des clés API différentes et avoir des modèles de tarification différents.

• model :

  • Type : string
  • Par défaut : Aucun
  • Description : Le modèle à utiliser pour les fonctionnalités d'IA d'Intlayer.
  • Exemple : 'gpt-4o-2024-11-20'
  • Note : Le modèle spécifique à utiliser varie selon le fournisseur.

• temperature :

  • Type : number
  • Par défaut : Aucun
  • Description : La température contrôle l'aléatoire des réponses de l'IA.
  • Exemple : 0.1
  • Note : Une température plus élevée rendra l'IA plus créative et moins prévisible.

• apiKey :

  • Type : string
  • Par défaut : Aucun
  • Description : Votre clé API pour le fournisseur sélectionné.
  • Exemple : process.env.OPENAI_API_KEY
  • Note : Important : Les clés API doivent être gardées secrètes et ne doivent pas être partagées publiquement. Veuillez vous assurer de les conserver dans un endroit sécurisé, comme des variables d'environnement.

• applicationContext :

  • Type : string
  • Par défaut : Aucun
  • Description : Fournit un contexte supplémentaire sur votre application au modèle d'IA, l'aidant à générer des traductions plus précises et contextuellement appropriées. Cela peut inclure des informations sur le domaine de votre application, le public cible, le ton ou une terminologie spécifique.

Configuration de la compilation

Paramètres qui contrôlent la manière dont Intlayer optimise et construit l'internationalisation de votre application.

Les options de compilation s'appliquent aux plugins @intlayer/babel et @intlayer/swc.

En mode développement, Intlayer utilise des imports statiques pour les dictionnaires afin de simplifier l'expérience de développement.

Lorsqu'il est optimisé, Intlayer remplacera les appels aux dictionnaires pour optimiser le découpage, de sorte que le bundle final importe uniquement les dictionnaires réellement utilisés.

Propriétés

• optimize :

  • Type : boolean
  • Par défaut : process.env.NODE_ENV === 'production'
  • Description : Contrôle si la compilation doit être optimisée.
  • Exemple : true
  • Note : Lorsqu'activé, Intlayer remplacera tous les appels aux dictionnaires pour optimiser le découpage. Ainsi, le bundle final n'importera que les dictionnaires utilisés. Tous les imports resteront des imports statiques pour éviter un traitement asynchrone lors du chargement des dictionnaires.
  • Note : Intlayer remplacera tous les appels de useIntlayer par le mode défini via l'option importMode et getIntlayer par getDictionary.
  • Note : Cette option repose sur les plugins @intlayer/babel et @intlayer/swc.
  • Note : Assurez-vous que toutes les clés sont déclarées statiquement dans les appels useIntlayer. Par exemple useIntlayer('navbar').

• importMode :

  • Type : 'static' | 'dynamic' | 'live'
  • Défaut : 'static'
  • Description : Contrôle la manière dont les dictionnaires sont importés.
  • Exemple : 'dynamic'
  • Note : Modes disponibles :
    • "static" : Les dictionnaires sont importés statiquement. Remplace useIntlayer par useDictionary.
    • "dynamic" : Les dictionnaires sont importés dynamiquement en utilisant Suspense. Remplace useIntlayer par useDictionaryDynamic.
  • "live" : Les dictionnaires sont récupérés dynamiquement en utilisant l'API de synchronisation en direct. Remplace useIntlayer par useDictionaryFetch.
  • Note : Les imports dynamiques reposent sur Suspense et peuvent légèrement impacter les performances de rendu.
  • Note : Si désactivé, toutes les locales seront chargées en une seule fois, même si elles ne sont pas utilisées.
  • Note : Cette option dépend des plugins @intlayer/babel et @intlayer/swc.
  • Note : Assurez-vous que toutes les clés sont déclarées statiquement dans les appels à useIntlayer. Par exemple useIntlayer('navbar').
  • Note : Cette option sera ignorée si optimize est désactivé.
  • Note : Si réglé sur "live", seuls les dictionnaires incluant du contenu distant et marqués avec le drapeau "live" seront transformés en mode live. Les autres seront importés dynamiquement en mode "dynamic" pour optimiser le nombre de requêtes fetch et les performances de chargement.
  • Note : Le mode live utilisera l'API de synchronisation live pour récupérer les dictionnaires. Si l'appel API échoue, les dictionnaires seront importés dynamiquement en mode "dynamic".
  • Note : Cette option n'affectera pas les fonctions getIntlayer, getDictionary, useDictionary, useDictionaryAsync et useDictionaryDynamic.

• traversePattern :

  • Type : string[]
  • Par défaut : ['**/*.{js,ts,mjs,cjs,jsx,tsx,mjx,cjx}', '!**/node_modules/**']
  • Description : Modèles qui définissent quels fichiers doivent être parcourus lors de l'optimisation.
    • Exemple : ['src/**/*.{ts,tsx}', '../ui-library/**/*.{ts,tsx}', '!**/node_modules/**']
  • Note : Utilisez ceci pour limiter l'optimisation aux fichiers de code pertinents et améliorer les performances de construction.
  • Note : Cette option sera ignorée si optimize est désactivé.
  • Note : Utilisez un motif glob.

Historique de la documentation

• Description : Modèles qui définissent quels fichiers doivent être parcourus lors de l'optimisation.
• Exemple : ['src/**/*.{ts,tsx}', '../ui-library/**/*.{ts,tsx}', '!**/node_modules/**']
• Note : Utilisez ceci pour limiter l'optimisation aux fichiers de code pertinents et améliorer les performances de la construction.
• Note : Cette option sera ignorée si optimize est désactivé.
• Note : Utilisez un motif glob.

Historique de la documentation