Archivo de Contenido

¿Qué es un Archivo de Contenido?

Un archivo de contenido en Intlayer es un archivo que contiene definiciones de diccionarios.
Estos archivos declaran el contenido de texto de tu aplicación, traducciones y recursos.
Los archivos de contenido son procesados por Intlayer para generar diccionarios.

Los diccionarios serán el resultado final que tu aplicación importará usando el hook useIntlayer.

Conceptos Clave

Diccionario

Un diccionario es una colección estructurada de contenido organizada por claves. Cada diccionario contiene:

• Clave: Un identificador único para el diccionario
• Contenido: Los valores reales del contenido (texto, números, objetos, etc.)
• Metadatos: Información adicional como título, descripción, etiquetas, etc.

Archivo de Contenido

Ejemplo de archivo de contenido:

import { type ReactNode } from "react";
import {
  t,
  enu,
  plural,
  cond,
  nest,
  md,
  insert,
  file,
  type Dictionary,
} from "intlayer";

interface Content {
  imbricatedContent: {
    imbricatedContent2: {
      stringContent: string;
      numberContent: number;
      booleanContent: boolean;
      javaScriptContent: string;
    };
  };
  multilingualContent: string;
  quantityContent: string;
  pluralContent: string;
  conditionalContent: string;
  markdownContent: never;
  htmlContent: never;
  externalContent: string;
  insertionContent: string;
  nestedContent: string;
  fileContent: string;
  jsxContent: ReactNode;
}

export default {
  key: "page",
  content: {
    imbricatedContent: {
      imbricatedContent2: {
        stringContent: "Hola Mundo",
        numberContent: 123,
        booleanContent: true,
        javaScriptContent: `${process.env.NODE_ENV}`,
      },
    },
    multilingualContent: t({
      en: "English content",
      "en-GB": "English content (UK)",
      fr: "French content",
      es: "Contenido en español",
    }),
    quantityContent: enu({
      "<-1": "Menos de menos un coche",
      "-1": "Menos un coche",
      "0": "Sin coches",
      "1": "Un coche",
      ">5": "Algunos coches",
      ">19": "Muchos coches",
    }),
    pluralContent: plural({
      one: "One car",
      other: "{{count}} cars",
    }),
    conditionalContent: cond({
      true: "La validación está habilitada",
      false: "La validación está deshabilitada",
    }),
    insertionContent: insert("¡Hola {{name}}!"),
    nestedContent: nest(
      "navbar", // La clave del diccionario para anidar
      "login.button" // [Opcional] La ruta al contenido para anidar
    ),
    fileContent: file("./path/to/file.txt"),
    externalContent: fetch("https://example.com").then((res) => res.json()),
    markdownContent: md("# Ejemplo de Markdown"),
    htmlContent: html("<p>Hello <strong>World</strong></p>"),

    /*
     * Solo disponible usando `react-intlayer` o `next-intlayer`
     */
    jsxContent: <h1>Mi título</h1>,
  },
} satisfies Dictionary<Content>; // [opcional] Dictionary es genérico y te permite reforzar el formato de tu diccionario

Nodos de Contenido

Los nodos de contenido son los bloques de construcción del contenido del diccionario. Pueden ser:

• Valores primitivos: cadenas, números, booleanos, null, undefined
• Nodos tipados: Tipos especiales de contenido como traducciones, condiciones, markdown, etc.
• Funciones: Contenido dinámico que puede evaluarse en runtime ver Obtención de Funciones
• Contenido Plural: Ver Contenido Plural Ver Contenido Plural
• Contenido anidado: Referencias a otros diccionarios

Tipos de Contenido

Intlayer soporta varios tipos de contenido a través de nodos tipados:

• Contenido de Traducción: Texto multilingüe con valores específicos por localidad ver Contenido de Traducción
• Contenido Condicional: Contenido condicional basado en expresiones booleanas ver Contenido Condicional
• Contenido de Enumeración: Contenido que varía según valores enumerados ver Contenido de Enumeración
• Contenido de Inserción: Contenido que puede ser insertado en otro contenido ver Contenido de Inserción
• Contenido Markdown: Contenido de texto enriquecido en formato Markdown ver Contenido Markdown
• Contenido HTML: Contenido HTML enriquecido con componentes personalizados opcionales ver Contenido HTML
• Contenido Anidado: Referencias a otros diccionarios ver Contenido Anidado
• Contenido de Género: Contenido que varía según el género ver Contenido de Género
• Contenido de Archivo: Referencias a archivos externos ver Contenido de Archivo

Estructura del Diccionario

Un diccionario en Intlayer se define mediante el tipo Dictionary y contiene varias propiedades que controlan su comportamiento:

Propiedades Requeridas

key (string)

El identificador del diccionario. Si varios diccionarios tienen la misma clave, Intlayer los fusionará automáticamente.

Use la convención de nomenclatura kebab-case (por ejemplo, "about-page-meta").

Content (string | number | boolean | object | array | function)

La propiedad content contiene los datos reales del diccionario y soporta:

• Valores primitivos: cadenas, números, booleanos, null, undefined
• Nodos tipados: Tipos de contenido especiales usando las funciones auxiliares de Intlayer
• Objetos anidados: Estructuras de datos complejas
• Arrays: Colecciones de contenido
• Funciones: Evaluación dinámica de contenido

Propiedades Opcionales

title (string)

Título legible para humanos del diccionario que ayuda a identificarlo en editores y sistemas CMS. Esto es particularmente útil cuando se gestionan grandes cantidades de diccionarios o cuando se trabaja con interfaces de gestión de contenido.

Ejemplo:

{  key: "about-page-meta",  title: "Metadatos de la Página Acerca de",  content: { /* ... */ }}

description (string)

Descripción detallada que explica el propósito del diccionario, las pautas de uso y cualquier consideración especial. Esta descripción también se utiliza como contexto para la generación de traducciones asistida por IA, lo que la hace valiosa para mantener la calidad y consistencia de las traducciones.

Ejemplo:

{  key: "about-page-meta",  description: [    "Este diccionario gestiona los metadatos de la Página Acerca de",    "Considera buenas prácticas para SEO:",    "- El título debe tener entre 50 y 60 caracteres",    "- La descripción debe tener entre 150 y 160 caracteres",  ].join('\n'),  content: { /* ... */ }}

tags (string[])

Array de cadenas para categorizar y organizar diccionarios. Las etiquetas proporcionan contexto adicional y pueden usarse para filtrar, buscar u organizar diccionarios en editores y sistemas CMS.

Ejemplo:

{  key: "about-page-meta",  tags: ["metadata", "about-page", "seo"],  content: { /* ... */ }}

format ('intlayer' | 'icu' | 'i18next')

Especifica el formateador a utilizar para el contenido del diccionario. Esto permite usar diferentes sintaxis de formateo de mensajes.

• 'intlayer': El formateador Intlayer por defecto.
• 'icu': Usa el formateo de mensajes ICU.
• 'i18next': Usa el formateo de mensajes i18next.

Ejemplo:

{  key: "my-dictionary",  format: "icu",  content: {    message: "Hello {name}, you have {count, plural, one {# message} other {# messages}}"  }}

locale (LocalesValues)

Transforma el diccionario en un diccionario por localización donde cada campo declarado en el contenido se transformará automáticamente en un nodo de traducción. Cuando esta propiedad está establecida:

• El diccionario se trata como un diccionario de un solo idioma
• Cada campo se convierte en un nodo de traducción para ese idioma específico
• NO debes usar nodos de traducción (t()) en el contenido cuando uses esta propiedad
• Si falta, el diccionario se tratará como un diccionario multilingüe

Consulta Declaración de contenido por idioma en Intlayer para más información.

Ejemplo:

// Diccionario por idioma{  "key": "about-page",  "locale": "en",  "content": {    "title": "About Us", // Esto se convierte en un nodo de traducción para 'en'    "description": "Learn more about our company"  }}

schema (SchemaKeys)

El esquema del contenido del diccionario. Si se establece, el contenido se validará contra este esquema. Esto te permite imponer una estructura específica para el contenido de tu diccionario usando esquemas de validación personalizados definidos en tu configuración de Intlayer.

Ejemplo:

import { z } from "zod";export default {  schemas: {    "seo-metadata": z.object({      title: z.string().min(50).max(60),      description: z.string().min(150).max(160),    }),  },};

import { type Dictionary } from "intlayer";const aboutPageMetaContent = {  key: "about-page-meta",  schema: "seo-metadata",  content: {    title: "About Our Company - Learn More About Us",    description: "Discover our company's mission, values, and team.",  },} satisfies Dictionary;export default aboutPageMetaContent;

location ('local' | 'remote' | 'hybrid' | string)

Indica la ubicación del diccionario y controla cómo se sincroniza con el CMS:

• 'local': El diccionario se gestiona solo localmente. No se enviará al CMS remoto. Use esto para contenido que debe permanecer en su codebase.
• 'remote': El diccionario se gestiona solo remotamente. Una vez enviado al CMS, se desvinculará del archivo local. En el momento de cargar el contenido, el diccionario remoto se obtendrá del CMS. Un archivo .content con ubicación remote será ignorado después del envío inicial.
• 'hybrid': El diccionario se gestiona tanto localmente como remotamente. Una vez enviado al CMS, permanecerá sincronizado, los cambios del archivo local se envían al CMS, y los cambios remotos pueden recuperarse en el archivo local.
• string (p. ej., 'plugin'): El diccionario es gestionado por un plugin o una fuente personalizada. Cuando intente enviarlo, el sistema le preguntará qué hacer.

Ejemplo:

{  key: "about-page",  location: "local", // El contenido permanece solo en su codebase  content: {    title: "About Us"  }}

autoFill (AutoFill)

Instrucciones para rellenar automáticamente el contenido del diccionario desde fuentes externas. Esto puede configurarse globalmente en intlayer.config.ts o por diccionario. Soporta múltiples formatos:

• true: Habilita el auto-relleno para todas las locales
• string: Ruta a un solo archivo o plantilla con variables
• object: Rutas de archivos por localización

Ejemplos:

// Habilitar para todas las locales{  "autoFill": true}// Archivo único{  "autoFill": "./translations/aboutPage.content.json"}// Plantilla con variables{  "autoFill": "/messages/{{locale}}/{{key}}/{{fileName}}.content.json"}// Configuración detallada por localización{  "autoFill": {    "en": "./translations/en/aboutPage.content.json",    "fr": "./translations/fr/aboutPage.content.json",    "es": "./translations/es/aboutPage.content.json"  }}

Variables disponibles:

• {{locale}} – Código de la localización (por ejemplo, fr, es)
• {{fileName}} – Nombre del archivo (por ejemplo, example)
• {{key}} – Clave del diccionario (por ejemplo, example)

Consulta Configuración de Auto-Relleno en Intlayer para más información.

priority (número)

Indica la prioridad del diccionario para la resolución de conflictos. Cuando varios diccionarios tienen la misma clave, el diccionario con el número de prioridad más alto sobrescribirá a los demás. Esto es útil para gestionar jerarquías de contenido y sobreescrituras.

Ejemplo:

// Diccionario base{  key: "welcome-message",  priority: 1,  content: { message: "¡Bienvenido!" }}// Diccionario de sobreescritura{  key: "welcome-message",  priority: 10,  content: { message: "¡Bienvenido a nuestro servicio premium!" }}// Esto anulará el diccionario base

Propiedades del CMS

version (cadena)

Identificador de versión para diccionarios remotos. Ayuda a rastrear qué versión del diccionario se está utilizando actualmente, especialmente útil cuando se trabaja con sistemas de gestión de contenido remotos.

importMode ('static' | 'dynamic' | 'fetch')

El modo de importación determina cómo se importa tu diccionario en tu aplicación.

• 'static': El diccionario se importa estáticamente en tiempo de compilación (build time). Este es el modo predeterminado.
• 'dynamic': El diccionario se importa dinámicamente en runtime usando la API de suspense.
• 'fetch': El diccionario se importa dinámicamente usando la API de sincronización en vivo.

Si se establece, esta propiedad anula el importMode global definido en la propiedad dictionarydeintlayer.config.ts``.

Propiedades del Sistema (Generadas automáticamente)

Estas propiedades son generadas automáticamente por Intlayer y no deben ser modificadas manualmente:

$schema (string)

Esquema JSON utilizado para la validación de la estructura del diccionario. Añadido automáticamente por Intlayer para asegurar la integridad del diccionario.

id (string)

Para diccionarios remotos, este es el identificador único del diccionario en el servidor remoto. Se usa para obtener y gestionar contenido remoto.

localId (LocalDictionaryId)

Identificador único para diccionarios locales. Generado automáticamente por Intlayer para ayudar a identificar el diccionario y determinar si es local o remoto, junto con su ubicación.

localIds (LocalDictionaryId[])

Para diccionarios fusionados, este arreglo contiene los IDs de todos los diccionarios que fueron fusionados juntos. Útil para rastrear la fuente del contenido fusionado.

filePath (string)

La ruta del archivo del diccionario local, indicando de qué archivo .content se generó el diccionario. Ayuda con la depuración y el seguimiento de la fuente.

versions (string[])

Para diccionarios remotos, este arreglo contiene todas las versiones disponibles del diccionario. Ayuda a rastrear qué versiones están disponibles para su uso.

autoFilled (true)

Indica si el diccionario ha sido auto-rellenado desde fuentes externas. En caso de conflictos, los diccionarios base sobrescribirán a los diccionarios auto-rellenados.

Tipos de Nodos de Contenido

Intlayer proporciona varios tipos especializados de nodos de contenido que extienden los valores primitivos básicos:

Contenido de Traducción (t)

Contenido multilingüe que varía según la localidad:

import { t } from "intlayer";// TypeScript/JavaScriptmultilingualContent: t({  en: "Welcome to our website",  fr: "Bienvenue sur notre site web",  es: "Bienvenido a nuestro sitio web",});

Ver Contenido de Traducción (t) Doc para más información.

Contenido Condicional (cond)

Contenido que cambia basado en condiciones booleanas:

import { cond } from "intlayer";conditionalContent: cond({  true: "User is logged in",  false: "Please log in to continue",});

Ver Contenido Condicional (cond) Doc para más información.

Contenido de Enumeración (enu)

Contenido que varía según valores enumerados:

import { enu } from "intlayer";statusContent: enu({  pending: "Su solicitud está pendiente",  approved: "Su solicitud ha sido aprobada",  rejected: "Su solicitud ha sido rechazada",});

Ver Contenido de Enumeración (enu) Doc para más información.

Contenido Plural (plural)

Contenido que varía según las reglas de plural:

import { plural } from "intlayer";pluralContent: plural({  one: "One car",  other: "{{count}} cars",});

Ver Contenido Plural Doc para más información.

Contenido de Inserción (insert)

Contenido que puede ser insertado en otro contenido:

import { insert } from "intlayer";insertionContent: insert("Este texto puede ser insertado en cualquier lugar");

Ver Contenido de Inserción (insert) Doc para más información.

Contenido Anidado (nest)

Referencias a otros diccionarios:

import { nest } from "intlayer";nestedContent: nest("about-page");

Ver Contenido Anidado (nest) Doc para más información.

Contenido Markdown (md)

Contenido de texto enriquecido en formato Markdown:

import { md } from "intlayer";markdownContent: md(  "# Bienvenido\n\nEste es un texto en **negrita** con [enlaces](https://example.com)");

Ver Contenido Markdown (md) Doc para más información.

Contenido HTML (html)

Contenido HTML enriquecido que puede usar etiquetas estándar o componentes personalizados:

import { html, file, t } from "intlayer";// HTML en líneahtmlContent: html("<p>Hello <strong>World</strong></p>");// HTML por localización desde archivos externoslocalizedHtmlContent: t({  en: html(file("./content.en.html")),  es: html(file("./content.es.html")),});

Ver Contenido HTML (html) Doc para más información.

Contenido según género (gender)

Contenido que varía según el género:

import { gender } from "intlayer";genderContent: gender({  male: "Él es un desarrollador",  female: "Ella es una desarrolladora",  other: "Ellos son desarrolladores",});

Ver Contenido según género (gender) Doc para más información.

Contenido de archivo (file)

Referencias a archivos externos:

import { file } from "intlayer";fileContent: file("./path/to/content.txt");

Ver Contenido de archivo (file) Doc para más información.

Creación de archivos de contenido

Estructura básica de un archivo de contenido

Un archivo de contenido exporta un objeto por defecto que cumple con el tipo Dictionary:

// example.content.tsimport { t, cond, nest, md, insert, file } from "intlayer";export default {  key: "welcome-page",  title: "Contenido de la página de bienvenida",  description:    "Contenido para la página principal de bienvenida que incluye la sección hero y características",  tags: ["página", "bienvenida", "página principal"],  content: {    hero: {      title: t({        en: "Welcome to Our Platform",        fr: "Bienvenue sur Notre Plateforme",        es: "Bienvenido a Nuestra Plataforma",      }),      subtitle: t({        en: "Build amazing applications with ease",        fr: "Construisez des applications incroyables avec facilité",        es: "Construye aplicaciones increíbles con facilidad",      }),      cta: cond({        true: t({          en: "Get Started",          fr: "Commencer",          es: "Comenzar",        }),        false: t({          en: "Sign Up",          fr: "S'inscrire",          es: "Registrarse",        }),      }),    },    features: [      {        title: t({          en: "Easy to Use",          fr: "Facile à Utiliser",          es: "Fácil de Usar",        }),        description: t({          en: "Intuitive interface for all skill levels",          fr: "Interface intuitive pour tous les niveaux",          es: "Interfaz intuitiva para todos los niveles",        }),      },    ],    documentation: nest("documentation"),    readme: file("./README.md"),  },} satisfies Dictionary;

Archivo de Contenido JSON

También puedes crear archivos de contenido en formato JSON:

{  "key": "welcome-page",  "title": "Contenido de la Página de Bienvenida",  "description": "Contenido para la página principal de bienvenida",  "tags": ["page", "welcome"],  "content": {    "hero": {      "title": {        "nodeType": "translation",        "translation": {          "en": "Bienvenido a Nuestra Plataforma",          "fr": "Bienvenue sur Notre Plateforme"        }      },      "subtitle": {        "nodeType": "translation",        "translation": {          "en": "Cree aplicaciones increíbles con facilidad",          "fr": "Construisez des applications incroyables avec facilité"        }      }    }  }}

Archivo de Contenido Markdown

---key: welcome-pagelocale: entitle: Welcome Page Contentdescription: Content for the main welcome pagetags:  - page  - welcome---# Welcome to Our Platform## Build amazing applications with ease

Archivo de Contenido YAML

key: welcome-pagetitle: Welcome Page Contentdescription: Content for the main welcome pagelocale: "en"tags:  - page  - welcomecontent:  hero:    title: Welcome to Our Platform    subtitle: Build amazing applications with ease

Archivos de Contenido por Localización

Para diccionarios por localización, especifique la propiedad locale:

// welcome-page.en.content.tsexport default {  key: "welcome-page",  locale: "en",  content: {    hero: {      title: "Bienvenido a Nuestra Plataforma",      subtitle: "Cree aplicaciones increíbles con facilidad",    },  },} satisfies Dictionary;

// welcome-page.fr.content.tsexport default {  key: "welcome-page",  locale: "fr",  content: {    hero: {      title: "Bienvenue sur Notre Plateforme",      subtitle: "Construisez des applications incroyables avec facilité",    },  },} satisfies Dictionary;

Extensiones de Archivos de Contenido

Intlayer te permite personalizar las extensiones para tus archivos de declaración de contenido. Esta personalización ofrece flexibilidad para gestionar proyectos a gran escala y ayuda a evitar conflictos con otros módulos.

Extensiones Predeterminadas

Por defecto, Intlayer vigila todos los archivos con las siguientes extensiones para declaraciones de contenido:

• .content.json
• .content.json5
• .content.jsonc
• .content.ts
• .content.tsx
• .content.js
• .content.jsx
• .content.mjs
• .content.mjx
• .content.cjs
• .content.cjx
• .content.md
• .content.mdx
• .content.yaml
• .content.yml

Estas extensiones predeterminadas son adecuadas para la mayoría de las aplicaciones. Sin embargo, cuando tienes necesidades específicas, puedes definir extensiones personalizadas para optimizar el proceso de compilación y reducir el riesgo de conflictos con otros componentes.

Para personalizar las extensiones de archivo que Intlayer utiliza para identificar los archivos de declaración de contenido, puedes especificarlas en el archivo de configuración de Intlayer. Este enfoque es beneficioso para proyectos a gran escala donde limitar el alcance del proceso de vigilancia mejora el rendimiento de la compilación.

Conceptos Avanzados

Fusión de Diccionarios

Cuando múltiples diccionarios tienen la misma clave, Intlayer los fusiona automáticamente. El comportamiento de la fusión depende de varios factores:

• Prioridad: Los diccionarios con valores de priority más altos sobrescriben a aquellos con valores más bajos
• Auto-relleno vs Base: Los diccionarios base sobrescriben a los diccionarios auto-rellenados
• Ubicación: Los diccionarios locales sobrescriben a los diccionarios remotos (cuando las prioridades son iguales)

Seguridad de Tipos

Intlayer proporciona soporte completo de TypeScript para archivos de contenido:

// Define tu tipo de contenidointerface WelcomePageContent {  hero: {    title: string;    subtitle: string;    cta: string;  };  features: Array<{    title: string;    description: string;  }>;}// Úsalo en tu diccionarioexport default {  key: "welcome-page",  content: {    // TypeScript proporcionará autocompletado y verificación de tipos    hero: {      title: "Welcome",      subtitle: "Build amazing apps",      cta: "Get Started",    },  },} satisfies Dictionary<WelcomePageContent>;

Imbricación de Nodos

Puedes sin problema imbricar funciones dentro de otras.

Ejemplo:

import { t, enu, cond, nest, md, type Dictionary } from "intlayer";

const getName = async () => "John Doe";

export default {
  key: "page",
  content: {
    // `getIntlayer('page','en').hiMessage` devuelve `['Hi', ' ', 'John Doe']`
    hiMessage: [
      t({
        en: "Hi",
        fr: "Salut",
        es: "Hola",
      }),
      " ",
      getName(),
    ],
    // Contenido compuesto imbricando condición, enumeración y contenido multilingüe
    // `getIntlayer('page','en').advancedContent(true)(10)` devuelve 'Multiple items found'
    advancedContent: cond({
      true: enu({
        "0": t({
          en: "No items found",
          fr: "Aucun article trouvé",
          es: "No se encontraron artículos",
        }),
        "1": t({
          en: "One item found",
          fr: "Un article trouvé",
          es: "Se encontró un artículo",
        }),
        ">1": t({
          en: "Multiple items found",
          fr: "Plusieurs articles trouvés",
          es: "Se encontraron múltiples artículos",
        }),
      }),
      false: t({
        en: "No valid data available",
        fr: "Aucune donnée valide disponible",
        es: "No hay datos válidos disponibles",
      }),
    }),
  },
} satisfies Dictionary;

Mejores Prácticas

1. Convenciones de Nomenclatura:

   • Usa kebab-case para las claves del diccionario ("about-page-meta")
   • Agrupa contenido relacionado bajo el mismo prefijo de clave

2. Organización del Contenido:

   • Mantén el contenido relacionado junto en el mismo diccionario
   • Usa objetos anidados para organizar estructuras de contenido complejas
   • Aprovecha las etiquetas para la categorización
   • Usa autoFill para completar automáticamente las traducciones faltantes

3. Rendimiento:

   • Ajusta la configuración del contenido para limitar el alcance de los archivos observados
   • Usa diccionarios en vivo solo cuando sean necesarias actualizaciones en tiempo real (por ejemplo, pruebas A/B, etc.)
   • Asegúrate de que el plugin de transformación de compilación (@intlayer/swc o @intlayer/babel) esté habilitado para optimizar el diccionario en tiempo de compilación (build time)