Documentación de Configuración de Intlayer

import { Locales, type IntlayerConfig } from "intlayer";
import { nextjsRewrite } from "intlayer/routing";
import { syncJSON } from "@intlayer/sync-json-plugin";
import { z } from "zod";

/**
 * Ejemplo de archivo de configuración de Intlayer que muestra todas las opciones disponibles.
 */
const config: IntlayerConfig = {
  /**
   * Configuración de los ajustes de internacionalización (internationalization).
   */
  internationalization: {
    /**
     * Lista de localidades (locales) admitidas en la aplicación.
     * Predeterminado: [Locales.ENGLISH]
     */
    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],

    /**
     * Lista de localidades obligatorias (required) que deben definirse en cada diccionario.
     * Si está vacío, todas las localidades son obligatorias en modo `strict`.
     * Predeterminado: []
     */
    requiredLocales: [Locales.ENGLISH],

    /**
     * Nivel de rigor (strictness) para el contenido internacionalizado.
     * - "strict": Error si falta alguna localidad declarada o si no está declarada.
     * - "inclusive": Advertencia si falta una localidad declarada.
     * - "loose": Acepta cualquier localidad existente.
     * Predeterminado: "inclusive"
     */
    strictMode: "inclusive",

    /**
     * Localidad predeterminada utilizada como recurso (fallback) en caso de que no se encuentre la localidad solicitada.
     * Predeterminado: Locales.ENGLISH
     */
    defaultLocale: Locales.ENGLISH,
  },

  /**
   * Ajustes que controlan las operaciones de diccionarios (dictionary) y el comportamiento de respaldo.
   */
  dictionary: {
    /**
     * Controla cómo se importan los diccionarios.
     * - "static": Importado estáticamente en el momento de la compilación.
     * - "dynamic": Importado dinámicamente utilizando Suspense.
     * - "fetch": Recuperado dinámicamente mediante el Live Sync API.
     * Predeterminado: "static"
     */
    importMode: "static",

    /**
     * Estrategia para rellenar automáticamente las traducciones faltantes mediante IA.
     * Puede ser un valor booleano o un patrón de ruta para guardar el contenido rellenado.
     * Predeterminado: true
     */
    fill: true,

    /**
     * Ubicación física de los archivos de diccionario.
     * - "local": Almacenado en el sistema de archivos local.
     * - "remote": Almacenado en el CMS de Intlayer.
     * - "hybrid": Almacenado tanto localmente como en el CMS de Intlayer.
     * - "plugin" (o cualquier cadena personalizada): Proporcionada por un complemento o fuente personalizada.
     * Predeterminado: "local"
     */
    location: "local",

    /**
     * Si el contenido debe transformarse automáticamente (p. ej., Markdown a HTML).
     * Predeterminado: false
     */
    contentAutoTransformation: false,
  },

  /**
   * Configuración de enrutamiento (routing) y middleware.
   */
  routing: {
    /**
     * Estrategia de enrutamiento de localidades.
     * - "prefix-no-default": Prefija todo excepto la localidad predeterminada (p. ej., /dashboard, /fr/dashboard).
     * - "prefix-all": Prefija todas las localidades (p. ej., /en/dashboard, /fr/dashboard).
     * - "no-prefix": Sin localidad en la URL.
     * - "search-params": Utiliza ?locale=...
     * Predeterminado: "prefix-no-default"
     */
    mode: "prefix-no-default",

    /**
     * Activa el proxy de enrutamiento de locales de Intlayer (middleware).
     * Gestiona la detección de locale, redirecciones y reescrituras en dev, preview y SSR.
     * - sin definir (auto): los servidores de dev y preview mantienen el enrutamiento
     *   guiado por la URL ignorando el locale almacenado en cookies y cabeceras.
     *   Los prefijos se siguen resolviendo, el locale se sigue persistiendo y la
     *   detección Accept-Language se sigue aplicando. En producción se comporta como `true`.
     * - true: comportamiento completo en todos los entornos.
     * - false: sin enrutamiento de locales.
     * Por defecto: undefined (auto)
     */
    enableProxy: undefined,

    /**
     * Dónde almacenar la localidad seleccionada por el usuario.
     * Opciones: 'cookie', 'localStorage', 'sessionStorage', 'header' o una combinación de estos.
     * Predeterminado: ['cookie', 'header']
     */
    storage: ["cookie", "header"],

    /**
     * Ruta base para las URL de la aplicación.
     * Predeterminado: ""
     */
    basePath: "",

    /**
     * Reglas de reescritura de URL personalizadas para rutas específicas por localidad.
     */
    rewrite: nextjsRewrite({
      "/[locale]/about": {
        en: "/[locale]/about",
        fr: "/[locale]/a-propos",
      },
    }),

    /**
     * Mapea las localidades a los nombres de host de dominio para el enrutamiento basado en dominios.
     * Las URL para estas localidades serán absolutas (p. ej., https://intlayer.cn/).
     * El dominio implica la localidad, por lo que no se añade ningún prefijo de localidad a la ruta.
     * Predeterminado: undefined
     */
    domains: {
      en: "intlayer.org",
      zh: "intlayer.cn",
    },
  },

  /**
   * Ajustes relacionados con la búsqueda y procesamiento de archivos de contenido (content).
   */
  content: {
    /**
     * Extensiones de archivo para escanear en busca de diccionarios.
     * Predeterminado: ['.content.ts', '.content.js', '.content.json', etc.]
     */
    fileExtensions: [".content.ts", ".content.js", ".content.json"],

    /**
     * Directorios donde se encuentran los archivos .content.
     * Predeterminado: ["."]
     */
    contentDir: ["src"],

    /**
     * Ubicación del código fuente (code).
     * Se usa para la optimización de la compilación y transformación del código.
     * Predeterminado: ["."]
     */
    codeDir: ["src"],

    /**
     * Patrones excluidos del escaneo.
     * Predeterminado: ['node_modules', '.intlayer', etc.]
     */
    excludedPath: ["node_modules"],

    /**
     * Si se deben monitorear los cambios y reconstruir los diccionarios durante el desarrollo.
     * Predeterminado: true en modo de desarrollo
     */
    watch: true,

    /**
     * Comando utilizado para formatear los archivos .content recién creados / actualizados.
     */
    formatCommand: 'npx prettier --write "{{file}}"',
  },

  /**
   * Configuración del Editor Visual (Visual Editor).
   */
  editor: {
    /**
     * Si el editor visual está habilitado.
     * Predeterminado: false
     */
    enabled: true,

    /**
     * La URL de su aplicación para la validación de origen.
     * Predeterminado: ""
     */
    applicationURL: "http://localhost:3000",

    /**
     * Puerto para el servidor del editor local.
     * Predeterminado: 8000
     */
    port: 8000,

    /**
     * URL pública del editor.
     * Predeterminado: "http://localhost:8000"
     */
    editorURL: "http://localhost:8000",

    /**
     * URL del CMS de Intlayer.
     * Predeterminado: "https://app.intlayer.org"
     */
    cmsURL: "https://app.intlayer.org",

    /**
     * URL de la API del Backend.
     * Predeterminado: "https://back.intlayer.org"
     */
    backendURL: "https://back.intlayer.org",

    /**
     * Activa la sincronización de contenido en tiempo real (Live Sync).
     * Predeterminado: false
     */
    liveSync: true,
  },

  /**
   * Configuración de analíticas (analytics).
   */
  analytics: {
    /**
     * Si la recopilación de analíticas está habilitada (vistas de página, exposiciones de contenido, eventos A/B).
     * Requiere que `@intlayer/analytics` esté instalado y que `editor.clientId` esté configurado para la atribución.
     * Predeterminado: true
     */
    enabled: true,

    /**
     * Milisegundos entre los envíos por lotes automáticos al backend.
     * Predeterminado: 20000
     */
    flushInterval: 20000,

    /**
     * Fracción de sesiones a registrar, de 0 (ninguna) a 1 (todas).
     * Predeterminado: 1
     */
    sampleRate: 1,
  },

  /**
   * Ajustes de traducción y construcción basados en IA.
   */
  ai: {
    /**
     * Proveedor de IA que se utilizará.
     * Opciones: 'openai', 'anthropic', 'mistral', 'deepseek', 'gemini', 'ollama', 'openrouter', 'alibaba', 'fireworks', 'groq', 'huggingface', 'bedrock', 'googlevertex', 'togetherai', 'lmstudio', 'moonshotai'
     * Predeterminado: 'openai'
     */
    provider: "openai",

    /**
     * Modelo del proveedor seleccionado que se utilizará.
     */
    model: "gpt-4o",

    /**
     * Clave de API del proveedor (API key).
     */
    apiKey: process.env.OPENAI_API_KEY,

    /**
     * Contexto global para guiar a la IA al generar traducciones.
     */
    applicationContext: "Esta es una aplicación de reserva de viajes.",

    /**
     * URL de ruta base para la API de IA.
     */
    baseURL: "http://localhost:3000",

    /**
     * Serialización de datos (Data Serialization)
     *
     * Opciones:
     * - "json": Por defecto, robusto; consume más tokens.
     * - "toon": consume menos tokens, puede no ser tan consistente como el JSON.
     *
     * Predeterminado: "json"
     */
    dataSerialization: "json",
  },

  /**
   * Ajustes de compilación (build) y optimización.
   */
  build: {
    /**
     * Modo de ejecución de compilación.
     * - "auto": Se compila automáticamente durante la compilación de la aplicación.
     * - "manual": Requiere un comando de compilación explícito.
     * Predeterminado: "auto"
     */
    mode: "auto",

    /**
     * Si se debe optimizar el paquete final (bundle) eliminando los diccionarios no utilizados.
     * Predeterminado: true en producción
     */
    optimize: true,

    /**
     * Minificar los diccionarios para reducir el tamaño del bundle.
     * Predeterminado: false
     *
     * Nota:
     * - Esta opción será ignorada si `optimize` está desactivado.
     * - Esta opción será ignorada si `editor.enabled` es verdadero.
     */
    minify: true,

    /**
     * Purgar las claves no utilizadas en los diccionarios.
     * Predeterminado: false
     *
     * Nota:
     * - Esta opción será ignorada si `optimize` está desactivado.
     */
    purge: true,

    /**
     * Agrupar los fragmentos de diccionario por configuración regional según el
     * límite de división de código que los usa, para que una página cargada de
     * forma diferida obtenga su contenido en una sola petición.
     * Predeterminado: true
     *
     * Nota:
     * - Solo se aplica a los diccionarios que usan `importMode: 'dynamic'`.
     */
    chunkGrouping: true,

    /**
     * Cargar un diccionario junto con el fragmento que lo usa, en lugar de
     * obtenerlo una vez que ese fragmento se renderiza. Los lectores se renderizan
     * de forma síncrona en lugar de suspenderse, por lo que navegar ya no muestra
     * un parpadeo de carga.
     * Predeterminado: true
     *
     * Nota:
     * - Solo se espera la configuración regional resuelta, por lo que la página
     *   solo descarga el idioma que muestra.
     */
    dictionariesPreload: true,

    /**
     * Formato de salida para los archivos de diccionario generados.
     * Predeterminado: ['cjs', 'esm']
     */
    outputFormat: ["cjs", "esm"],

    /**
     * Indica si la compilación debe verificar los tipos de TypeScript.
     * Predeterminado: false
     */
    checkTypes: false,
  },

  /**
   * Configuración del registrador (Logger).
   */
  log: {
    /**
     * Nivel de registro (logging).
     * - "default": Registro estándar.
     * - "verbose": Registro detallado de depuración (debug).
     * - "disabled": Desactiva el registro.
     * Predeterminado: "default"
     */
    mode: "default",

    /**
     * Prefijo para todos los mensajes de registro.
     * Predeterminado: "[intlayer]"
     */
    prefix: "[intlayer]",
  },

  /**
   * Configuración del sistema (System Configuration - Para uso avanzado)
   */
  system: {
    /**
     * Directorio para almacenar diccionarios localizados.
     */
    dictionariesDir: ".intlayer/dictionary",

    /**
     * Directorio para el aumento de módulos de TypeScript (module augmentation).
     */
    moduleAugmentationDir: ".intlayer/types",

    /**
     * Directorio para almacenar diccionarios no fusionados.
     */
    unmergedDictionariesDir: ".intlayer/unmerged_dictionary",

    /**
     * Directorio para almacenar tipos de diccionarios.
     */
    typesDir: ".intlayer/types",

    /**
     * Directorio donde se almacenan los archivos principales de la aplicación.
     */
    mainDir: ".intlayer/main",

    /**
     * Directorio donde se almacenan los archivos de configuración.
     */
    configDir: ".intlayer/config",

    /**
     * Directorio donde se almacenan los archivos de caché.
     */
    cacheDir: ".intlayer/cache",
  },

  /**
   * Configuración del Compilador (Compiler Configuration - Para uso avanzado)
   */
  compiler: {
    /**
     * Indica si el compilador (compiler) debe estar habilitado.
     *
     * - false: Deshabilita el compilador.
     * - true: Habilita el compilador.
     * - "build-only": Omite el compilador durante el desarrollo y acelera el tiempo de arranque.
     *
     * Predeterminado: false
     */
    enabled: true,

    /**
     * Define la ruta para los archivos de salida. Reemplaza `outputDir`.
     *
     * - Las rutas con `./` se resuelven en relación con el directorio del componente.
     * - Las rutas con `/` se resuelven en relación con la raíz del proyecto (`baseDir`).
     *
     * - Al incluir la variable `{{locale}}` en la ruta, se activará la creación de diccionarios separados por idioma (locale).
     *
     * Ejemplo:
     * ```ts
     * {
     *   // Crear archivos .content.ts multilingües al lado del componente
     *   output: ({ fileName, extension }) => `./${fileName}${extension}`,
     *
     *   // output: './{{fileName}}{{extension}}', // Equivalente usando cadena de plantilla
     * }
     * ```
     *
     * ```ts
     * {
     *   // Crear JSON centralizados por idioma en la raíz del proyecto
     *   output: ({ key, locale }) => `/locales/${locale}/${key}.content.json`,
     *
     *   // output: '/locales/{{locale}}/{{key}}.content.json', // Equivalente usando cadena de plantilla
     * }
     * ```
     *
     * Lista de variables:
     *   - `fileName`: Nombre del archivo.
     *   - `key`: Clave de contenido.
     *   - `locale`: Localidad del contenido.
     *   - `extension`: Extensión del archivo.
     *   - `componentFileName`: Nombre del archivo del componente.
     *   - `componentExtension`: Extensión del archivo del componente.
     *   - `format`: Formato del diccionario.
     *   - `componentFormat`: Formato del diccionario del componente.
     *   - `componentDirPath`: Ruta del directorio del componente.
     */
    output: ({ locale, key }) => `compiler/${locale}/${key}.json`,

    /**
     * Indica si los componentes deben guardarse después de ser transformados.
     *
     * - Si es `true`, el compilador reescribirá el archivo del componente en el disco. Por lo tanto, la transformación será permanente y el compilador omitirá la transformación en el próximo proceso. De esta manera, el compilador puede transformar la aplicación y luego puede ser eliminado.
     *
     * - Si es `false`, el compilador inyectará la llamada a la función `useIntlayer()` en el código solo en la salida del build, y mantendrá intacta la base de código original. La transformación se realizará solo en memoria.
     */
    saveComponents: false,

    /**
     * Solo inserta el contenido en el archivo generado. Útil para salida de JSON por idioma para i18next o ICU MessageFormat.
     */
    noMetadata: false,

    /**
     * Prefijo de clave de diccionario
     */
    dictionaryKeyPrefix: "", // Agregue un prefijo opcional a las claves de diccionario extraídas
  },

  /**
   * Esquemas personalizados (schemas) para validar el contenido de los diccionarios.
   */
  schemas: {
    "my-schema": z.object({
      title: z.string(),
    }),
  },

  /**
   * Configuración del diccionario.
   */
  dictionary: {
    /**
     * Controla cómo se importan los diccionarios.
     * - "static": Importado estáticamente en el momento de compilación.
     * - "dynamic": Importado dinámicamente usando Suspense.
     * - "fetch": Obtenido dinámicamente a través de la API de sincronización en vivo.
     */
    importMode: "static",

    /**
     * El formato de mensaje predeterminado para todos los diccionarios del proyecto.
     * - 'intlayer': Formato intlayer nativo (predeterminado).
     * - 'icu': Formato de mensaje ICU.
     * - 'i18next': Formato i18next.
     * - 'vue-i18n': Formato Vue I18n.
     * - 'po': Formato GNU Gettext PO.
     */
    format: "icu",
  },

  /**
   * Configuración de plugins.
   */
  plugins: [
    syncJSON({
      format: "icu",
      source: ({ locale }) => `./messages/${locale}.json`,
    }),
  ],
};

export default config;

routing: {
  mode: "prefix-no-default", // Estrategia de respaldo
  rewrite: nextjsRewrite({
    "/about": {
      en: "/about",
      fr: "/a-propos",
    },
    "/product/[slug]": {
      en: "/product/[slug]",
      fr: "/produit/[slug]",
    },
    "/blog/[category]/[id]": {
      en: "/blog/[category]/[id]",
      fr: "/journal/[category]/[id]",
    },
  }),
}

import { Locales, type IntlayerConfig } from "intlayer";
// intlayer.config.ts
const config: IntlayerConfig = {
  internationalization: {
    locales: ["en", "fr", "es"],
    defaultLocale: "en",
  },
  routing: {
    mode: "prefix-no-default",
    storage: "localStorage",
    basePath: "",
  },
};

export default config;

import { Locales, type IntlayerConfig } from "intlayer";
// intlayer.config.ts
const config: IntlayerConfig = {
  internationalization: {
    locales: ["en", "fr", "es"],
    defaultLocale: "en",
  },
  routing: {
    mode: "prefix-no-default",
    storage: [
      {
        type: "localStorage",
        name: "user-locale",
      },
      {
        type: "cookie",
        name: "user-locale",
        secure: true,
        sameSite: "strict",
        httpOnly: false,
      },
    ],
    basePath: "",
  },
};

export default config;

import { Locales, type IntlayerConfig } from "intlayer";
// intlayer.config.ts
const config: IntlayerConfig = {
  internationalization: {
    locales: ["en", "fr", "es"],
    defaultLocale: "en",
  },
  routing: {
    mode: "search-params",
    storage: "localStorage",
    basePath: "",
  },
};

export default config;

import { Locales, type IntlayerConfig } from "intlayer";
// intlayer.config.ts
const config: IntlayerConfig = {
  internationalization: {
    locales: ["en", "fr", "es"],
    defaultLocale: "en",
  },
  routing: {
    mode: "no-prefix",
    storage: {
      type: "sessionStorage",
      name: "app-locale",
    },
    basePath: "/my-app",
  },
};

export default config;

// intlayer.config.ts
import { nextjsRewrite } from "intlayer/routing";

const config: IntlayerConfig = {
  internationalization: {
    locales: ["en", "fr"],
    defaultLocale: "en",
  },
  routing: {
    mode: "prefix-no-default", // Estrategia de respaldo para rutas que no se reescriben
    storage: "cookie",
    rewrite: nextjsRewrite({
      "/about": {
        en: "/about",
        fr: "/a-propos",
      },
      "/product/[slug]": {
        en: "/product/[slug]",
        fr: "/produit/[slug]",
      },
      "/blog/[category]/[id]": {
        en: "/blog/[category]/[id]",
        fr: "/journal/[category]/[id]",
      },
    }),
  },
};

export default config;

dictionary: {
  fill: {
    en: "/locales/en/{{key}}.content.json",
    fr: ({ key }) => `/locales/fr/${key}.content.json`,
    es: false,
  },
};