Documentación de Configuración de Intlayer

Descripción General

Los archivos de configuración de Intlayer permiten la personalización de varios aspectos del plugin, como la internacionalización, middleware y manejo de contenido. Este documento proporciona una descripción detallada de cada propiedad en la configuración.

Soporte de Archivos de Configuración

Intlayer acepta formatos de archivo de configuración JSON, JS, MJS y TS:

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

Ejemplo de archivo de configuración

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH],  },  content: {    contentDir: ["src", "../ui-library"],  },  middleware: {    noPrefix: false,  },  editor: {    applicationURL: "https://example.com",  },  ai: {    apiKey: process.env.OPENAI_API_KEY,    applicationContext: "This is a test application",  },  build: {    importMode: "dynamic",  },};export default config;

Referencia de Configuración

Las siguientes secciones describen las diversas configuraciones disponibles para Intlayer.

Configuración de Internacionalización

Define configuraciones relacionadas con la internacionalización, incluyendo los idiomas disponibles y el idioma predeterminado para la aplicación.

Propiedades

• locales:

  • Tipo: string[]
  • Por defecto: ['en']
  • Descripción: La lista de idiomas soportados en la aplicación.
  • Ejemplo: ['en', 'fr', 'es']
• requiredLocales:
  • Tipo: string[]
  • Por defecto: []
  • Descripción: La lista de idiomas requeridos en la aplicación.
  • Ejemplo: []
  • Nota: Si está vacío, todos los idiomas son requeridos en modo strict.
  • Nota: Asegúrese de que los idiomas requeridos también estén definidos en el campo locales.

• strictMode:

  • Tipo: string
  • Por defecto: inclusive
  • Descripción: Asegura implementaciones sólidas de contenido internacionalizado usando TypeScript.
  • Nota: Si se establece en "strict", la función de traducción t requerirá que cada idioma declarado esté definido. Si falta un idioma o si un idioma no está declarado en su configuración, lanzará un error.
  • Nota: Si se establece en "inclusive", la función de traducción t requerirá que cada idioma declarado esté definido. Si falta un idioma, mostrará una advertencia. Pero aceptará si un idioma no está declarado en su configuración, pero existe.
  • Nota: Si se establece en "loose", la función de traducción t aceptará cualquier idioma existente.

• defaultLocale:

  • Tipo: string
  • Por defecto: 'en'
  • Descripción: El idioma predeterminado utilizado como respaldo si no se encuentra el idioma solicitado.
  • Ejemplo: 'en'
  • Nota: Esto se utiliza para determinar el idioma cuando no se especifica ninguno en la URL, cookie o encabezado.

Configuración del Editor

Define configuraciones relacionadas con el editor integrado, incluyendo el puerto del servidor y el estado activo.

Propiedades

• applicationURL:

  • Tipo: string
  • Por defecto: http://localhost:3000
  • Descripción: La URL de la aplicación. Se utiliza para restringir el origen del editor por razones de seguridad.
  • Ejemplo:
    • 'http://localhost:3000'
    • 'https://example.com'
    • process.env.INTLAYER_EDITOR_URL
  • Nota: La URL de la aplicación. Se utiliza para restringir el origen del editor por razones de seguridad. Si se establece en '*', el editor es accesible desde cualquier origen.

• port:

  • Tipo: number
  • Por defecto: 8000
  • Descripción: El puerto utilizado por el servidor del editor visual.

• editorURL:

  • Tipo: string
  • Por defecto: 'http://localhost:8000'
  • Descripción: La URL del servidor del editor. Se utiliza para restringir el origen del editor por razones de seguridad.
    • 'http://localhost:3000'
    • 'https://example.com'
    • process.env.INTLAYER_EDITOR_URL
  • Nota: La URL del servidor del editor para acceder desde la aplicación. Se utiliza para restringir los orígenes que pueden interactuar con la aplicación por razones de seguridad. Si se establece en '*', el editor es accesible desde cualquier origen. Debe configurarse si el puerto cambia o si el editor está alojado en un dominio diferente.

• cmsURL:

  • Tipo: string
  • Por defecto: 'https://intlayer.org'
  • Descripción: La URL del CMS de Intlayer.
  • Ejemplo: 'https://intlayer.org'
  • Nota: La URL del CMS de Intlayer.

• backendURL:

  • Tipo: string
  • Por defecto: https://back.intlayer.org
  • Descripción: La URL del servidor backend.
  • Ejemplo: http://localhost:4000

• enabled:

  • Tipo: boolean
  • Por defecto: true
  • Descripción: Indica si la aplicación interactúa con el editor visual.
  • Ejemplo: process.env.NODE_ENV !== 'production'
  • Nota: Si es verdadero, el editor podrá interactuar con la aplicación. Si es falso, el editor no podrá interactuar con la aplicación. En cualquier caso, el editor solo puede ser habilitado por el editor visual. Deshabilitar el editor para entornos específicos es una forma de reforzar la seguridad.

• clientId:

  • Tipo: string | undefined
  • Por defecto: undefined
  • Descripción: clientId y clientSecret permiten que los paquetes de Intlayer se autentiquen con el backend utilizando autenticación oAuth2. Se utiliza un token de acceso para autenticar al usuario relacionado con el proyecto. Para obtener un token de acceso, vaya a https://intlayer.org/dashboard/project y cree una cuenta.
  • Ejemplo: true
  • Nota: Importante: El clientId y clientSecret deben mantenerse en secreto y no compartirse públicamente. Asegúrese de mantenerlos en un lugar seguro, como variables de entorno.

• clientSecret:

  • Tipo: string | undefined
  • Por defecto: undefined
  • Descripción: clientId y clientSecret permiten que los paquetes de intlayer se autentiquen con el backend utilizando autenticación oAuth2. Se utiliza un token de acceso para autenticar al usuario relacionado con el proyecto. Para obtener un token de acceso, vaya a https://intlayer.org/dashboard/project y cree una cuenta.
  • Ejemplo: true
  • Nota: Importante: El clientId y clientSecret deben mantenerse en secreto y no compartirse públicamente. Asegúrese de mantenerlos en un lugar seguro, como variables de entorno.

• liveSync:

  • Tipo: boolean
  • Por defecto: false
  • Descripción: Indica si la aplicación debe recargar automáticamente las configuraciones de idioma cuando se detecta un cambio.
  • Ejemplo: true
  • Nota: Por ejemplo, cuando se agrega o actualiza un nuevo diccionario, la aplicación actualizará el contenido para mostrar en la página.
  • Nota: Debido a que la recarga automática necesita una conexión continua al servidor, solo está disponible para clientes del plan enterprise.

• dictionaryPriorityStrategy:

  • Tipo: string
  • Por defecto: 'local_first'
  • Descripción: La estrategia para priorizar diccionarios en caso de que existan diccionarios locales y remotos. Si se establece en 'distant_first', la aplicación priorizará los diccionarios remotos sobre los locales. Si se establece en 'local_first', la aplicación priorizará los diccionarios locales sobre los remotos.
  • Ejemplo: 'distant_first'

Configuración de Middleware

Configuraciones que controlan el comportamiento del middleware, incluyendo cómo la aplicación maneja cookies, encabezados y prefijos de URL para la gestión de idiomas.

Propiedades

• headerName:

  • Tipo: string
  • Por defecto: 'x-intlayer-locale'
  • Descripción: El nombre del encabezado HTTP utilizado para determinar la configuración regional.
  • Ejemplo: 'x-custom-locale'
  • Nota: Esto es útil para la determinación de la configuración regional basada en API.

• cookieName:

  • Tipo: string
  • Por defecto: 'intlayer-locale'
  • Descripción: El nombre de la cookie utilizada para almacenar la configuración regional.
  • Ejemplo: 'custom-locale'
  • Nota: Se utiliza para mantener la configuración regional entre sesiones.

• prefixDefault:

  • Tipo: boolean
  • Por defecto: false
  • Descripción: Indica si se debe incluir la configuración regional predeterminada en la URL.
  • Ejemplo: true
  • Nota:
    • Si true y defaultLocale = 'en': path = /en/dashboard o /fr/dashboard
    • Si false y defaultLocale = 'en': path = /dashboard o /fr/dashboard

• basePath:

  • Tipo: string
  • Por defecto: ''
  • Descripción: La ruta base para las URLs de la aplicación.
  • Ejemplo: '/my-app'
  • Nota:
    • Si la aplicación está alojada en https://example.com/my-app
    • La ruta base es '/my-app'
    • La URL será https://example.com/my-app/en
    • Si la ruta base no está configurada, la URL será https://example.com/en

• serverSetCookie:

  • Tipo: string
  • Por defecto: 'always'
  • Descripción: Regla para establecer la cookie de configuración regional en el servidor.
  • Opciones: 'always', 'never'
  • Ejemplo: 'never'
  • Nota: Controla si la cookie de configuración regional se establece en cada solicitud o nunca.

• noPrefix:

  • Tipo: boolean
  • Por defecto: false
  • Descripción: Indica si se debe omitir el prefijo de configuración regional en las URLs.
  • Ejemplo: true
  • Nota:
    • Si true: Sin prefijo en la URL
    • Si false: Prefijo en la URL
    • Ejemplo con basePath = '/my-app':
      • Si noPrefix = false: La URL será https://example.com/my-app/en
      • Si noPrefix = true: La URL será https://example.com

• detectLocaleOnPrefetchNoPrefix:

  • Tipo: boolean
  • Por defecto: false
  • Descripción: Controla si la detección de configuración regional ocurre durante las solicitudes de precarga de Next.js.
  • Ejemplo: true
  • Nota: Esta configuración afecta cómo Next.js maneja la precarga de configuración regional:
    • Escenario de ejemplo:
      • El idioma del navegador del usuario es 'fr'
      • La página actual es /fr/about
      • El enlace precarga /about
    • Con detectLocaleOnPrefetchNoPrefix: true:
      • La precarga detecta la configuración regional 'fr' desde el navegador
      • Redirige la precarga a /fr/about
    • Con detectLocaleOnPrefetchNoPrefix: false (por defecto):
      • La precarga usa la configuración regional predeterminada
      • Redirige la precarga a /en/about (asumiendo que 'en' es la predeterminada)
    • Cuándo usar true:
      • Tu aplicación usa enlaces internos no localizados (ej. <a href="/about">)
      • Quieres comportamiento consistente de detección de configuración regional entre solicitudes normales y de precarga
    • Cuándo usar false (por defecto):
      • Tu aplicación usa enlaces con prefijo de configuración regional (ej. <a href="/fr/about">)
      • Quieres optimizar el rendimiento de precarga
      • Quieres evitar bucles de redirección potenciales

Configuración de Contenido

Configuraciones relacionadas con el manejo de contenido dentro de la aplicación, incluyendo nombres de directorios, extensiones de archivos y configuraciones derivadas.

Propiedades

• watch:

  • Tipo: boolean
  • Por defecto: process.env.NODE_ENV === 'development'
  • Descripción: Indica si Intlayer debe observar cambios en los archivos de declaración de contenido en la aplicación para reconstruir los diccionarios relacionados.

• fileExtensions:

  • Tipo: string[]
  • Por defecto: ['.content.ts', '.content.js', '.content.cjs', '.content.mjs', '.content.json', '.content.tsx', '.content.jsx']
  • Descripción: Extensiones de archivo a buscar al construir diccionarios.
  • Ejemplo: ['.data.ts', '.data.js', '.data.json']
  • Nota: Personalizar las extensiones de archivo puede ayudar a evitar conflictos.

• baseDir:

  • Tipo: string
  • Por defecto: process.cwd()
  • Descripción: El directorio base para el proyecto.
  • Ejemplo: '/path/to/project'
  • Nota: Esto se utiliza para resolver todos los directorios relacionados con Intlayer.

• dictionaryOutput:

  • Tipo: string[]
  • Por defecto: ['intlayer']
  • Descripción: El tipo de salida de diccionario a usar, por ejemplo, 'intlayer' o 'i18next'.

• contentDir:

  • Tipo: string[]
  • Por defecto: ['src']
  • Ejemplo: ['src', '../../ui-library', require.resolve("@my-package/content")]
  • Descripción: La ruta del directorio donde se almacena el contenido.

• dictionariesDir:

  • Tipo: string
  • Por defecto: '.intlayer/dictionaries'
  • Descripción: La ruta del directorio para almacenar resultados intermedios o de salida.

• moduleAugmentationDir:

  • Tipo: string
  • Por defecto: '.intlayer/types'
  • Descripción: Directorio para la ampliación de módulos, permitiendo mejores sugerencias en el IDE y verificación de tipos.
  • Ejemplo: 'intlayer-types'
  • Nota: Asegúrate de incluir esto en tsconfig.json.

• unmergedDictionariesDir:

  • Tipo: string
  • Por defecto: '.intlayer/unmerged_dictionary'
  • Descripción: El directorio para almacenar diccionarios no fusionados.
  • Ejemplo: 'translations'

• dictionariesDir:

  • Tipo: string
  • Por defecto: '.intlayer/dictionary'
  • Descripción: El directorio para almacenar diccionarios de localización.
  • Ejemplo: 'translations'

• i18nextResourcesDir:

  • Tipo: string
  • Por defecto: 'i18next_dictionary'
  • Descripción: El directorio para almacenar diccionarios de i18n.
  • Ejemplo: 'translations'
  • Nota: Asegúrate de que este directorio esté configurado para el tipo de salida i18next.

• typesDir:

  • Tipo: string
  • Por defecto: 'types'
  • Descripción: El directorio para almacenar tipos de diccionario.
  • Ejemplo: 'intlayer-types'

• mainDir:

  • Tipo: string
  • Por defecto: 'main'
  • Descripción: El directorio donde se almacenan los archivos principales de la aplicación.
  • Ejemplo: 'intlayer-main'

• excludedPath:

  • Tipo: string[]
  • Por defecto: ['node_modules']
  • Descripción: Directorios excluidos de la búsqueda de contenido.
  • Nota: Esta configuración aún no se utiliza, pero está planeada para futuras implementaciones.

Configuración del Logger

Configuraciones que controlan el logger, incluyendo el prefijo a usar.

Propiedades

• mode:

  • Tipo: string
  • Por defecto: default
  • Descripción: Indica el modo del logger.
  • Opciones: default, verbose, disabled
  • Ejemplo: default
  • Nota: El modo del logger. El modo verbose registrará más información, pero puede usarse con fines de depuración. El modo disabled desactivará el logger.

• prefix:

  • Tipo: string
  • Por defecto: '[intlayer] '
  • Descripción: El prefijo del logger.
  • Ejemplo: '[my custom prefix] '
  • Nota: El prefijo del logger.

Configuración de AI

Configuraciones que controlan las características de AI de Intlayer, incluyendo el proveedor, modelo y clave API. Esta configuración es opcional si estás registrado en el Panel de Intlayer usando una clave de acceso. Intlayer gestionará automáticamente la solución de AI más eficiente y rentable para tus necesidades. Usar las opciones predeterminadas asegura un mejor mantenimiento a largo plazo, ya que Intlayer se actualiza continuamente para usar los modelos más relevantes.

Si prefieres usar tu propia clave API o un modelo específico, puedes definir tu configuración personalizada de AI. Esta configuración de AI se usará globalmente en todo tu entorno Intlayer. Los comandos CLI usarán estas configuraciones como valores predeterminados para los comandos (por ejemplo, fill), así como el SDK, el Editor Visual y el CMS. Puedes sobrescribir estos valores predeterminados para casos específicos usando parámetros de comando. Intlayer admite múltiples proveedores de AI para mayor flexibilidad y elección. Los proveedores actualmente soportados son:

• OpenAI (predeterminado)
• Anthropic Claude
• Mistral AI
• DeepSeek
• Google Gemini
• Meta Llama

Propiedades

• provider:

  • Tipo: string
  • Por defecto: 'openai'
  • Descripción: El proveedor a usar para las características de AI de Intlayer.
  • Opciones: 'openai', 'anthropic', 'mistral', 'deepseek', 'gemini'
  • Ejemplo: 'anthropic'
  • Nota: Diferentes proveedores pueden requerir diferentes claves API y tener diferentes modelos de precios.

• model:

  • Tipo: string
  • Por defecto: Ninguno
  • Descripción: El modelo a usar para las características de AI de Intlayer.
  • Ejemplo: 'gpt-4o-2024-11-20'
  • Nota: El modelo específico a usar varía según el proveedor.

• temperature:

  • Tipo: number
  • Por defecto: Ninguno
  • Descripción: La temperatura controla la aleatoriedad de las respuestas de la IA.
  • Ejemplo: 0.1
  • Nota: Una temperatura más alta hará que la IA sea más creativa y menos predecible.

• apiKey:

  • Tipo: string
  • Por defecto: Ninguno
  • Descripción: Tu clave API para el proveedor seleccionado.
  • Ejemplo: process.env.OPENAI_API_KEY
  • Nota: Importante: Las claves API deben mantenerse en secreto y no compartirse públicamente. Asegúrate de mantenerlas en un lugar seguro, como variables de entorno.

• applicationContext:

  • Tipo: string
  • Por defecto: Ninguno
  • Descripción: Proporciona contexto adicional sobre tu aplicación al modelo de AI, ayudándolo a generar traducciones más precisas y contextualmente apropiadas. Esto puede incluir información sobre el dominio de tu aplicación, audiencia objetivo, tono o terminología específica.

Configuración de Compilación

Ajustes que controlan cómo Intlayer optimiza y compila la internacionalización de tu aplicación.

Las opciones de compilación se aplican a los plugins @intlayer/babel y @intlayer/swc.

En modo desarrollo, Intlayer utiliza importaciones estáticas para los diccionarios para simplificar la experiencia de desarrollo.

Al optimizar, Intlayer reemplazará las llamadas a los diccionarios para optimizar el chunking, de modo que el bundle final solo importe los diccionarios que realmente se utilizan.

Propiedades

• optimize:

  • Tipo: boolean
  • Valor por defecto: process.env.NODE_ENV === 'production'
  • Descripción: Controla si la compilación debe ser optimizada.
  • Ejemplo: true
  • Nota: Cuando está habilitado, Intlayer reemplazará todas las llamadas de diccionarios para optimizar el chunking. De esta manera, el bundle final solo importará los diccionarios que se utilizan. Todas las importaciones permanecerán como importaciones estáticas para evitar el procesamiento asíncrono al cargar los diccionarios.
  • Nota: Intlayer reemplazará todas las llamadas de useIntlayer con el modo definido por la opción importMode y getIntlayer con getDictionary.
  • Nota: Esta opción se basa en los plugins @intlayer/babel y @intlayer/swc.
  • Nota: Asegúrate de que todas las claves estén declaradas estáticamente en las llamadas useIntlayer. por ejemplo: useIntlayer('navbar').

• importMode:

  • Tipo: 'static' | 'dynamic' | 'async'
  • Valor por defecto: 'static'
  • Descripción: Controla cómo se importan los diccionarios.
  • Ejemplo: 'dynamic'
  • Nota: Modos disponibles:
    • "static": Los diccionarios se importan estáticamente. Reemplaza useIntlayer con useDictionary.
    • "dynamic": Los diccionarios se importan dinámicamente usando Suspense. Reemplaza useIntlayer con useDictionaryDynamic.
    • "async": Los diccionarios se importan dinámicamente de forma asíncrona. Reemplaza useIntlayer con await useDictionaryAsync.
  • Nota: Las importaciones dinámicas dependen de Suspense y pueden afectar ligeramente el rendimiento del renderizado.
  • Nota: Si está deshabilitado, todos los idiomas se cargarán a la vez, incluso si no se utilizan.
  • Nota: Esta opción se basa en los plugins @intlayer/babel y @intlayer/swc.
  • Nota: Asegúrate de que todas las claves estén declaradas estáticamente en las llamadas useIntlayer. por ejemplo: useIntlayer('navbar').
  • Nota: Esta opción será ignorada si optimize está deshabilitado.
  • Nota: En la mayoría de los casos, "dynamic" se usará para aplicaciones React, "async" para aplicaciones Vue.js.
  • Nota: Esta opción no afectará las funciones getIntlayer, getDictionary, useDictionary, useDictionaryAsync y useDictionaryDynamic.

• traversePattern:

  • Tipo: string[]
  • Valor por defecto: ['**/*.{js,ts,mjs,cjs,jsx,tsx,mjx,cjx}', '!**/node_modules/**']
  • Descripción: Patrones que definen qué archivos deben ser recorridos durante la optimización.
    • Ejemplo: ['src/**/*.{ts,tsx}', '../ui-library/**/*.{ts,tsx}', '!**/node_modules/**']
  • Nota: Usa esto para limitar la optimización a archivos de código relevantes y mejorar el rendimiento de la compilación.
  • Nota: Esta opción será ignorada si optimize está deshabilitado.
  • Nota: Usa patrón glob.

Historial de la documentación