intlayer: Paquete NPM para Gestionar la Declaración de Contenido Multilingüe (i18n)

Intlayer es un conjunto de paquetes diseñado específicamente para desarrolladores de JavaScript. Es compatible con frameworks como React, Next.js y Express.js.

El paquete intlayer te permite declarar tu contenido en cualquier lugar de tu código. Convierte las declaraciones de contenido multilingüe en diccionarios estructurados que se integran a la perfección en tu aplicación. Con TypeScript, Intlayer mejora tu desarrollo al proporcionar herramientas más fuertes y eficientes.

¿Por qué integrar Intlayer?

• Gestión de Contenido Potenciada por JavaScript: Aprovecha la flexibilidad de JavaScript para definir y gestionar tu contenido de manera eficiente.
• Entorno Seguro de Tipos: Aprovecha TypeScript para asegurar que todas tus definiciones de contenido sean precisas y sin errores.
• Archivos de Contenido Integrados: Mantén tus traducciones cerca de sus respectivos componentes, mejorando la mantenibilidad y la claridad.

Instalación

Instala el paquete necesario utilizando tu gestor de paquetes preferido:

npm install intlayer

Configura Intlayer

Intlayer proporciona un archivo de configuración para configurar tu proyecto. Coloca este archivo en la raíz de tu proyecto.

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [Locales.ENGLISH, Locales.FRENCH, Locales.SPANISH],    defaultLocale: Locales.ENGLISH,  },};export default config;

Para una lista completa de parámetros disponibles, consulta la documentación de configuración.

Ejemplo de uso

Con Intlayer, puedes declarar tu contenido de manera estructurada en cualquier parte de tu código.

Por defecto, Intlayer busca archivos con la extensión .content.{ts,tsx,js,jsx,mjs,cjs}.

Puedes modificar la extensión predeterminada configurando la propiedad contentDir en el archivo de configuración.

.├── intlayer.config.ts└── src    ├── ClientComponent    │   ├── index.content.ts    │   └── index.tsx    └── ServerComponent        ├── index.content.ts        └── index.tsx

Declara tu contenido

Aquí tienes un ejemplo de declaración de contenido:

import { type DeclarationContent, t } from "intlayer";const clientComponentContent = {  key: "client-component",  content: {    myTranslatedContent: t({      en: "Hello World",      fr: "Bonjour le monde",      es: "Hola Mundo",    }),    numberOfCar: enu({      "<-1": "Less than minus one car",      "-1": "Minus one car",      "0": "No cars",      "1": "One car",      ">5": "Some cars",      ">19": "Many cars",    }),  },} satisfies DeclarationContent;export default clientComponentContent;

Construye tus diccionarios

Puedes construir tus diccionarios utilizando el intlayer-cli.

npx intlayer build

Este comando escanea todos los archivos *.content.*, los compila y escribe los resultados en el directorio especificado en tu intlayer.config.ts (por defecto, ./.intlayer).

Una salida típica podría verse así:

.├── .intlayer│   ├── dictionary  # Contiene el diccionario de tu contenido│   │   ├── client-component.json│   │   └── server-component.json│   ├── main  # Contiene el punto de entrada de tu diccionario para ser usado en tu aplicación│   │   ├── dictionary.cjs│   │   └── dictionary.mjs│   └── types  # Contiene las definiciones de tipo autogeneradas de tu diccionario│       ├── client-component.d.ts│       └── server-component.d.ts└── types    └── intlayer.d.ts  # Contiene las definiciones de tipo autogeneradas de Intlayer

Construye recursos i18next

Intlayer puede configurarse para construir diccionarios para i18next. Para esto, necesitas agregar la siguiente configuración a tu archivo intlayer.config.ts:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  /* ... */  content: {    // Indica a Intlayer que genere archivos de mensajes para i18next    dictionaryOutput: ["i18next"],    // El directorio donde Intlayer escribirá tus archivos JSON de mensajes    i18nextResourcesDir: "./i18next/resources",  },};

Para una lista completa de parámetros disponibles, consulta la documentación de configuración.

Salida:

.└── i18next    └── resources        ├── en        │   ├── client-component.json        │   └── server-component.json        ├── es        │   ├── client-component.json        │   └── server-component.json        └── fr            ├── client-component.json            └── server-component.json

Por ejemplo, el es/client-component.json podría verse así:

{  "myTranslatedContent": "Hola Mundo",  "zero_numberOfCar": "No cars",  "one_numberOfCar": "One car",  "two_numberOfCar": "Two cars",  "other_numberOfCar": "Some cars"}

Construye diccionarios i18next o next-intl

Intlayer puede configurarse para construir diccionarios para i18next o next-intl. Para ello, necesitas agregar la siguiente configuración a tu archivo intlayer.config.ts:

import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  /* ... */  content: {    // Indica a Intlayer que genere archivos de mensajes para i18next    dictionaryOutput: ["next-intl"],    // El directorio donde Intlayer escribirá tus archivos JSON de mensajes    nextIntlMessagesDir: "./i18next/messages",  },};

Para una lista completa de parámetros disponibles, consulta la documentación de configuración.

Salida:

.└── intl    └── messages        ├── en        │   ├── client-component.json        │   └── server-component.json        ├── es        │   ├── client-component.json        │   └── server-component.json        └── fr            ├── client-component.json            └── server-component.json

Por ejemplo, el es/client-component.json podría verse así:

{  "myTranslatedContent": "Hola Mundo",  "zero_numberOfCar": "No cars",  "one_numberOfCar": "One car",  "two_numberOfCar": "Two cars",  "other_numberOfCar": "Some cars"}

Herramientas CLI

Intlayer proporciona una herramienta CLI para:

• auditar tus declaraciones de contenido y completar traducciones faltantes
• construir diccionarios a partir de tus declaraciones de contenido
• cargar y descargar diccionarios distantes desde tu CMS a tu proyecto local

Consulta intlayer-cli para más información.

Usa Intlayer en tu aplicación

Una vez que tu contenido esté declarado, puedes consumir tus diccionarios de Intlayer en tu aplicación.

Intlayer está disponible como un paquete para tu aplicación.

Aplicación React

Para usar Intlayer en tu aplicación React, puedes usar react-intlayer.

Aplicación Next.js

Para usar Intlayer en tu aplicación Next.js, puedes usar next-intlayer.

Aplicación Express

Para usar Intlayer en tu aplicación Express, puedes usar express-intlayer.

Funciones proporcionadas por el paquete intlayer

El paquete intlayer también proporciona algunas funciones para ayudarte a internacionalizar tu aplicación.

• getConfiguration()
• getTranslationContent()
• getEnumerationContent()
• getLocaleName()
• getLocaleLang()
• getHTMLTextDir()
• getPathWithoutLocale()
• getMultilingualUrls()
• getLocalizedUrl()
• getPathWithoutLocale()