Documentación de Configuración de Intlayer

Visió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

Archivo de configuración de ejemplo

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH], // locales soportados  },  content: {    autoFill: "./{{fileName}}.content.json", // archivo de contenido para autocompletar    contentDir: ["src", "../ui-library"], // directorios de contenido  },  middleware: {    noPrefix: false, // si se debe usar prefijo en middleware  },  editor: {    applicationURL: "https://example.com", // URL de la aplicación para el editor  },  ai: {    apiKey: process.env.OPENAI_API_KEY, // clave API para AI    applicationContext: "This is a test application", // contexto de la aplicación para AI  },  build: {    importMode: "dynamic", // modo de importación para build  },};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 locales disponibles y el local predeterminado para la aplicación.

Propiedades

• locales:

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

• strictMode:

  • Tipo: string
  • Por defecto: inclusive
  • Descripción: Garantiza implementaciones sólidas de contenido internacionalizado usando typescript.
  • Nota: Si se establece en "strict", la función de traducción t requerirá que cada uno de los locales declarados esté definido. Si falta un locale, o si un locale 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 uno de los locales declarados esté definido. Si falta un locale, lanzará una advertencia. Pero aceptará si un locale no está declarado en su configuración, pero existe.
  • Nota: Si se establece en "loose", la función de traducción t aceptará cualquier locale existente.

• defaultLocale:

  • Tipo: string
  • Por defecto: 'en'
  • Descripción: El locale predeterminado que se usa como respaldo si no se encuentra el locale solicitado.
  • Ejemplo: 'en'
  • Nota: Esto se usa para determinar el locale 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 usa 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 usa 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 usa 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 a la que se accede desde la aplicación. Se usa 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 se cambia el puerto 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 la autenticación oAuth2. Un token de acceso se usa para autenticar al usuario relacionado con el proyecto. Para obtener un token de acceso, visite 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 guardarlos 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 la 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. Por favor, asegúrese de mantenerlos en un lugar seguro, como variables de entorno.

• dictionaryPriorityStrategy:

  • Tipo: string
  • Por defecto: 'local_first'
  • Descripción: La estrategia para priorizar los diccionarios en caso de que estén presentes tanto diccionarios locales como 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'

• liveSync:

  • Tipo: boolean
  • Por defecto: false
  • Descripción: Indica si el servidor de la aplicación debe recargar en caliente el contenido de la aplicación cuando se detecta un cambio en el CMS / Editor Visual / Backend.
  • Ejemplo: true
  • Nota: Por ejemplo, cuando se añade o actualiza un nuevo diccionario, la aplicación actualizará el contenido para mostrarlo en la página.
  • Nota: La sincronización en vivo necesita externalizar el contenido de la aplicación a otro servidor. Esto significa que puede afectar ligeramente el rendimiento de la aplicación. Para limitar esto, recomendamos alojar la aplicación y el servidor de sincronización en vivo en la misma máquina. Además, la combinación de sincronización en vivo y optimize puede generar un número considerable de solicitudes al servidor de sincronización en vivo. Dependiendo de su infraestructura, recomendamos probar ambas opciones y su combinación.

• liveSyncPort:

  • Tipo: number
  • Por defecto: 4000
  • Descripción: El puerto del servidor de sincronización en vivo.
  • Ejemplo: 4000
  • Nota: El puerto del servidor de sincronización en vivo.

• liveSyncURL:

  • Tipo: string
  • Por defecto: 'http://localhost:{liveSyncPort}'
  • Descripción: La URL del servidor de sincronización en vivo.
  • Ejemplo: 'https://example.com'
  • Nota: Apunta a localhost por defecto, pero puede cambiarse a cualquier URL en el caso de un servidor de sincronización en vivo remoto.

Configuración del 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 locales.

Propiedades

• headerName:

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

• cookieName:

  • Tipo: string
  • Por defecto: 'intlayer-locale'
  • Descripción: El nombre de la cookie usada para almacenar el locale.
  • Ejemplo: 'custom-locale'
  • Nota: Se utiliza para mantener la localización a través de las sesiones.

• prefixDefault:

  • Tipo: boolean
  • Por defecto: false
  • Descripción: Indica si se debe incluir la localización por defecto en la URL.
  • Ejemplo: true
  • Nota:
    • Si es true y defaultLocale = 'en': ruta = /en/dashboard o /fr/dashboard
    • Si es false y defaultLocale = 'en': ruta = /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 no se establece la ruta base, la URL será https://example.com/en

• serverSetCookie:

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

• noPrefix:

  • Tipo: boolean
  • Por defecto: false
  • Descripción: Indica si se omite el prefijo de localización en las URLs.
  • Ejemplo: true
  • Nota:
    • Si es true: No hay prefijo en la URL
    • Si es false: Hay 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 la configuración regional ocurre durante las solicitudes de prefetch de Next.js.
  • Ejemplo: true
  • Nota: Esta configuración afecta cómo Next.js maneja el prefetch de locales:
    • Escenario de ejemplo:
      • El idioma del navegador del usuario es 'fr'
      • La página actual es /fr/about
      • El enlace hace prefetch de /about
    • Con detectLocaleOnPrefetchNoPrefix: true:
      • El prefetch detecta la configuración regional 'fr' desde el navegador
      • Redirige el prefetch a /fr/about
    • Con detectLocaleOnPrefetchNoPrefix: false (por defecto):
      • El prefetch usa la configuración regional por defecto
      • Redirige el prefetch a /en/about (asumiendo que 'en' es la predeterminada)
    • Cuándo usar true:
      • Su aplicación utiliza enlaces internos no localizados (por ejemplo, <a href="/about">)
      • Desea un comportamiento consistente en la detección de la configuración regional entre solicitudes regulares y de prefetch
    • Cuándo usar false (por defecto):
      • Su aplicación utiliza enlaces con prefijo de configuración regional (por ejemplo, <a href="/fr/about">)
      • Desea optimizar el rendimiento del prefetch
      • Desea evitar posibles bucles de redireccionamiento

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

• autoFill:

  • Tipo: boolean | string | { [key in Locales]?: string }
  • Por defecto: undefined
  • Descripción: Indica cómo debe completarse automáticamente el contenido usando IA. Puede declararse globalmente en el archivo intlayer.config.ts.
  • Ejemplo: true
  • Ejemplo: './{{fileName}}.content.json'
  • Ejemplo: { fr: './{{fileName}}.fr.content.json', es: './{{fileName}}.es.content.json' }
  • Nota: La configuración de auto completado. Puede ser:
    • booleano: Habilitar auto completado para todas las locales
    • cadena: Ruta a un solo archivo o plantilla con variables
    • objeto: Rutas de archivo por locale

• watch:

  • Tipo: boolean
  • Por defecto: process.env.NODE_ENV === 'development'
  • Descripción: Indica si Intlayer debe vigilar 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 que se buscan al construir los 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: '/ruta/al/proyecto'
  • Nota: Esto se usa para resolver todos los directorios relacionados con Intlayer.

• dictionaryOutput:

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

• contentDir:

  • Tipo: string[]
  • Por defecto: ['.']
  • 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 los diccionarios de localización.
  • Ejemplo: 'translations'

• i18nextResourcesDir:

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

• typesDir:

  • Tipo: string
  • Por defecto: 'types'
  • Descripción: El directorio para almacenar los 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á planificada para una implementación futura.

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 para propósitos 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 registrador.

Configuración de IA

Configuraciones que controlan las funciones de IA de Intlayer, incluyendo el proveedor, modelo y clave API.

Esta configuración es opcional si estás registrado en el Panel de Control de Intlayer usando una clave de acceso. Intlayer gestionará automáticamente la solución de IA 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 IA. Esta configuración de IA se utilizará globalmente en todo su 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. Puede anular estos valores predeterminados para casos de uso específicos utilizando parámetros de comando.

Intlayer admite múltiples proveedores de IA para una 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
  • Predeterminado: 'openai'
  • Descripción: El proveedor a utilizar para las funciones de IA de Intlayer.
  • Opciones: 'openai', 'anthropic', 'mistral', 'deepseek', 'gemini'
  • Ejemplo: 'anthropic'
  • Nota: Diferentes proveedores pueden requerir diferentes claves API y tener distintos modelos de precios.

• model:

  • Tipo: string
  • Por defecto: Ninguno
  • Descripción: El modelo a utilizar para las funciones de IA de Intlayer.
  • Ejemplo: 'gpt-4o-2024-11-20'
  • Nota: El modelo específico a utilizar 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: Su 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. Por favor, asegúrese de guardarlas en un lugar seguro, como variables de entorno.

• applicationContext:

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

Configuración de compilación

Configuraciones que controlan cómo Intlayer optimiza y construye la internacionalización de su aplicación.

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

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

Cuando está optimizado, Intlayer reemplazará las llamadas a diccionarios para optimizar el particionado, de modo que el paquete final solo importe los diccionarios que realmente se usan.

Propiedades

• optimize:

  • Tipo: boolean
  • 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 a diccionarios para optimizar el particionado. De esta forma, el paquete final solo importará los diccionarios que se usan. 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 a useIntlayer con el modo definido por la opción importMode y getIntlayer con getDictionary.
  • Nota: Esta opción depende de los plugins @intlayer/babel y @intlayer/swc.
  • Nota: Asegúrese de que todas las claves estén declaradas estáticamente en las llamadas a useIntlayer. Por ejemplo, useIntlayer('navbar').

• importMode:

  • Tipo: 'static' | 'dynamic' | 'live'
  • Por defecto: 'static'
  • Descripción: Controla cómo se importan los diccionarios.
  • Ejemplo: 'dynamic'
  • Nota: Modos disponibles:
    • "static": Los diccionarios se importan de forma estática. Reemplaza useIntlayer con useDictionary.
    • "dynamic": Los diccionarios se importan dinámicamente usando Suspense. Reemplaza useIntlayer con useDictionaryDynamic.
    • "live": Los diccionarios se obtienen dinámicamente usando la API de sincronización en vivo. Reemplaza useIntlayer con useDictionaryFetch.
  • Nota: Las importaciones dinámicas dependen de Suspense y pueden afectar ligeramente el rendimiento del renderizado.
  • Nota: Si está deshabilitado, todos los locales se cargarán a la vez, incluso si no se usan.
  • Nota: Esta opción depende de los plugins @intlayer/babel y @intlayer/swc.
  • Nota: Asegúrese de que todas las claves estén declaradas estáticamente en las llamadas a useIntlayer. Por ejemplo, useIntlayer('navbar').
  • Nota: Esta opción será ignorada si optimize está deshabilitado.
  • Nota: Si se establece en "live", solo los diccionarios que incluyen contenido remoto y están marcados con la bandera "live" serán transformados en modo en vivo. Los demás se importarán dinámicamente en modo "dynamic" para optimizar el número de consultas fetch y el rendimiento de carga.
  • Nota: El modo en vivo utilizará la API de sincronización en vivo para obtener los diccionarios. Si la llamada a la API falla, los diccionarios se importarán dinámicamente en modo "dynamic".
  • Nota: Esta opción no afectará a las funciones getIntlayer, getDictionary, useDictionary, useDictionaryAsync y useDictionaryDynamic.

• traversePattern:

  • Tipo: string[]
  • 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: Utilice 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: Use patrón glob.

Historial de Documentación