intlayer_with_create_react_app.md

createdAt

2024-08-11

updatedAt

2026-05-31

title

Create React App i18n - Guía completa para traducir tu aplicación

description

Sin más i18next. La guía 2026 para crear una aplicación Create React App multilingüe (i18n). Traduce con agentes de IA y optimiza el tamaño del bundle, SEO y rendimiento.

keywords

Internacionalización

Documentación

Intlayer

Create React App

CRA

JavaScript

React

slugs

doc

environment

create-react-app

applicationTemplate

https://github.com/aymericzip/intlayer-react-cra-template

history

version	date	changes
8.9.0	2026-05-04	Actualizar el uso de la API useIntlayer de Solid para el acceso directo a las propiedades

version	date	changes
7.5.9	2025-12-30	Agregar comando init

version	date	changes
5.5.10	2025-06-29	Historial inicial

Traduce tu Create React App con Intlayer | Internacionalización (i18n)

Consulta Application Template en GitHub.

¿Qué es Intlayer?

Intlayer es una biblioteca innovadora y de código abierto para la internacionalización (i18n) diseñada para simplificar el soporte multilingüe en aplicaciones web modernas.

Con Intlayer, puedes:

Gestionar fácilmente las traducciones utilizando diccionarios declarativos a nivel de componente.
Localizar dinámicamente metadatos, rutas y contenido.
Garantizar soporte para TypeScript con tipos autogenerados, mejorando la autocompletación y la detección de errores.
Aprovechar características avanzadas, como la detección dinámica de locales y el cambio entre ellos.

Guía paso a paso para configurar Intlayer en una aplicación React

Instala los paquetes necesarios usando npm:

npm install intlayer react-intlayer react-scripts-intlayer
npx intlayer init

pnpm add intlayer react-intlayer react-scripts-intlayer
pnpm intlayer init

yarn add intlayer react-intlayer react-scripts-intlayer
yarn intlayer init

bun add intlayer react-intlayer react-scripts-intlayer
bun x intlayer init

intlayer

El paquete principal que proporciona herramientas de internacionalización para la gestión de configuración, traducción, declaración de contenido, transpilación y comandos CLI.
react-intlayer

El paquete que integra Intlayer con aplicaciones React. Proporciona proveedores de contexto y hooks para la internacionalización en React.
react-scripts-intlayer

Incluye los comandos y complementos react-scripts-intlayer para integrar Intlayer con aplicaciones basadas en Create React App. Estos complementos están basados en craco e incluyen configuración adicional para el empaquetador Webpack.

Crea un archivo de configuración para configurar los idiomas de tu aplicación:

import { Locales, type IntlayerConfig } from "intlayer";

const config: IntlayerConfig = {
  internationalization: {
    locales: [
      Locales.ENGLISH,
      Locales.FRENCH,
      Locales.SPANISH,
      // Tus otros locales
    ],
    defaultLocale: Locales.ENGLISH,
  },
};

export default config;

A través de este archivo de configuración, puedes configurar URLs localizadas, redirección de middleware, nombres de cookies, la ubicación y extensión de tus declaraciones de contenido, desactivar los logs de Intlayer en la consola y más. Para una lista completa de parámetros disponibles, consulta la documentación de configuración.

Cambia tus scripts para usar react-intlayer

  "scripts": {
    "build": "react-scripts-intlayer build",
    "start": "react-scripts-intlayer start",
    "transpile": "intlayer build"
  },

Los scripts react-scripts-intlayer están basados en CRACO. También puedes implementar tu propia configuración basada en el complemento craco de Intlayer. Ver ejemplo aquí.

Crea y gestiona tus declaraciones de contenido para almacenar traducciones:

import { t, type Dictionary } from "intlayer";
import React, { type ReactNode } from "react";

const appContent = {
  key: "app",
  content: {
    getStarted: t<ReactNode>({
      en: (
        <>
          Edit <code>src/App.tsx</code> and save to reload
        </>
      ),
      fr: (
        <>
          Éditez <code>src/App.tsx</code> et enregistrez pour recharger
        </>
      ),
      es: (
        <>
          Edita <code>src/App.tsx</code> y guarda para recargar
        </>
      ),
    }),
    reactLink: {
      href: "https://reactjs.org",
      content: t({
        en: "Learn React",
        fr: "Apprendre React",
        es: "Aprender React",
      }),
    },
  },
} satisfies Dictionary;

export default appContent;

const { t } = require("intlayer");

/** @type {import('intlayer').Dictionary} */
const appContent = {
  key: "app",
  content: {
    getStarted: t({
      en: "Get started by editing",
      fr: "Commencez par éditer",
      es: "Comience por editar",
    }),
    reactLink: {
      href: "https://reactjs.org",
      content: t({
        en: "Learn React",
        fr: "Apprendre React",
        es: "Aprender React",
      }),
    },
  },
};

module.exports = appContent;

Tus declaraciones de contenido pueden definirse en cualquier lugar de tu aplicación siempre que estén incluidas en el directorio contentDir (por defecto, ./src). Y coincidan con la extensión del archivo de declaración de contenido (por defecto, .content.{json,ts,tsx,js,jsx,mjs,cjs,md,mdx,yaml,yml}).

Para más detalles, consulta la documentación de declaración de contenido.

Si tu archivo de contenido incluye código TSX, deberías considerar importar import React from "react"; en tu archivo de contenido.

Accede a tus diccionarios de contenido en toda tu aplicación:

import logo from "./logo.svg";
import "./App.css";
import type { FC } from "react";
import { IntlayerProvider, useIntlayer } from "react-intlayer";

const AppContent: FC = () => {
  const content = useIntlayer("app");

  return (
    <div className="App">
      <img src={logo} className="App-logo" alt="logo" />

      {content.getStarted}
      <a
        className="App-link"
        href={content.reactLink.href.value}
        target="_blank"
        rel="noopener noreferrer"
      >
        {content.reactLink.content}
      </a>
    </div>
  );
};

const App: FC = () => (
  <IntlayerProvider>
    <AppContent />
  </IntlayerProvider>
);

export default App;

Nota: Si quieres usar tu contenido en un atributo de tipo string, como alt, title, href, aria-label, etc., debes llamar al valor de la función, así:

<img src="{content.image.src.value}" alt="{content.image.value}" />
<img src="{content.image.src.toString()}" alt="{content.image.toString()}" />
<img src="{String(content.image.src)}" alt="{String(content.image)}" />

Para aprender más sobre el hook useIntlayer, consulta la documentación.

Para cambiar el idioma de tu contenido, puedes usar la función setLocale proporcionada por el hook useLocale. Esta función te permite establecer el local de la aplicación y actualizar el contenido en consecuencia.

import { Locales } from "intlayer";
import { useLocale } from "react-intlayer";

const LocaleSwitcher = () => {
  const { setLocale } = useLocale();

  return (
    <button onClick={() => setLocale(Locales.English)}>
      Cambiar idioma a inglés
    </button>
  );
};

Para aprender más sobre el hook useLocale, consulta la documentación.

El propósito de este paso es crear rutas únicas para cada idioma. Esto es útil para SEO y URLs amigables con SEO. Ejemplo:

- https://example.com/about
- https://example.com/es/about
- https://example.com/fr/about

Por defecto, las rutas no tienen prefijo para la configuración regional predeterminada. Si deseas agregar un prefijo para la configuración regional predeterminada, puedes establecer la opción middleware.prefixDefault en true en tu configuración. Consulta la documentación de configuración para más información.

Para agregar enrutamiento por localeizado a tu aplicación, puedes crear un componente LocaleRouter que envuelva las rutas de tu aplicación y gestione el enrutamiento basado en la configuración regional. Aquí tienes un ejemplo usando React Router:

// Importando las dependencias y funciones necesarias
import { type Locales, configuration, getPathWithoutLocale } from "intlayer"; // Funciones y tipos de utilidad de 'intlayer'
// Funciones y tipos de utilidad de 'intlayer'
import type { FC, PropsWithChildren } from "react"; // Tipos de React para componentes funcionales y props
import { IntlayerProvider } from "react-intlayer"; // Proveedor para el contexto de internacionalización
import {
  BrowserRouter,
  Routes,
  Route,
  Navigate,
  useLocation,
} from "react-router-dom"; // Componentes del enrutador para gestionar la navegación

// Desestructurando configuración de Intlayer
const { internationalization, middleware } = configuration;
const { locales, defaultLocale } = internationalization;

/**
 * Un componente que maneja la localización y envuelve a los hijos con el contexto de local adecuado.
 * Gestiona la detección y validación del local basada en la URL.
 */
const AppLocalized: FC<PropsWithChildren<{ locale: Locales }>> = ({
  children,
  locale,
}) => {
  const { pathname, search } = useLocation(); // Obtener la ruta URL actual

  // Determinar el local actual, usando el predeterminado si no se proporciona
  const currentLocale = locale ?? defaultLocale;

  // Eliminar el prefijo del local de la ruta para construir una ruta base
  const pathWithoutLocale = getPathWithoutLocale(
    pathname // Ruta URL actual
  );

  /**
   * Si middleware.prefixDefault es true, el local predeterminado siempre debe estar prefijado.
   */
  if (middleware.prefixDefault) {
    // Validar el local
    if (!locale || !locales.includes(locale)) {
      // Redirigir al local predeterminado con la ruta actualizada
      return (
        <Navigate
          to={`/${defaultLocale}/${pathWithoutLocale}${search}`}
          replace // Reemplazar la entrada actual del historial con la nueva
        />
      );
    }

    // Envolver a los hijos con IntlayerProvider y establecer el local actual
    return (
      <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider>
    );
  } else {
    /**
     * Cuando middleware.prefixDefault es falso, el local predeterminado no está prefijado.
     * Asegurarse de que el local actual sea válido y no el local predeterminado.
     */
    if (
      currentLocale.toString() !== defaultLocale.toString() &&
      !locales
        .filter(
          (locale) => locale.toString() !== defaultLocale.toString() // Excluir el local predeterminado
        )
        .includes(currentLocale) // Verificar si el local actual está en la lista de locales válidos
    ) {
      // Redirigir a la ruta sin prefijo de local
      return <Navigate to={`${pathWithoutLocale}${search}`} replace />;
    }

    // Envolver a los hijos con el IntlayerProvider y establecer el local actual
    return (
      <IntlayerProvider locale={currentLocale}>{children}</IntlayerProvider>
    );
  }
};

/**
 * Un componente de enrutador que configura rutas específicas para locales.
 * Usa React Router para gestionar la navegación y renderizar componentes localizados.
 */
export const LocaleRouter: FC<PropsWithChildren> = ({ children }) => (
  <BrowserRouter>
    <Routes>
      {locales
        .filter(
          (locale) => middleware.prefixDefault || locale !== defaultLocale
        )
        .map((locale) => (
          <Route
            // Patrón de ruta para capturar el local (por ejemplo, /en/, /fr/) y coincidir con todas las rutas subsecuentes
            path={`/${locale}/*`}
            key={locale}
            element={<AppLocalized locale={locale}>{children}</AppLocalized>} // Envuelve a los hijos con la gestión de locales
          />
        ))}

      {
        // Si el prefijo del local predeterminado está deshabilitado, renderiza los hijos directamente en la ruta raíz
        !middleware.prefixDefault && (
          <Route
            path="*"
            element={
              <AppLocalized locale={defaultLocale}>{children}</AppLocalized>
            } // Envuelve a los hijos con la gestión de locales
          />
        )
      }
    </Routes>
  </BrowserRouter>
);

Luego, puedes usar el componente LocaleRouter en tu aplicación:

import { LocaleRouter } from "./components/LocaleRouter";
import type { FC } from "react";

// ... Tu componente AppContent

const App: FC = () => (
  <LocaleRouter>
    <AppContent />
  </LocaleRouter>
);

Para cambiar la URL cuando cambia el local, puedes usar la prop onLocaleChange proporcionada por el hook useLocale. Paralelamente, puedes usar los hooks useLocation y useNavigate de react-router-dom para actualizar la ruta URL.

import { useLocation, useNavigate } from "react-router-dom";
import {
  Locales,
  getHTMLTextDir,
  getLocaleName,
  getLocalizedUrl,
} from "intlayer";
import { useLocale } from "react-intlayer";
import { type FC } from "react";

const LocaleSwitcher: FC = () => {
  const { pathname, search } = useLocation(); // Obtiene la ruta URL actual. Ejemplo: /fr/about?foo=bar
  const navigate = useNavigate();

  const { locale, availableLocales, setLocale } = useLocale({
    onLocaleChange: (locale) => {
      // Construir la URL con el local actualizado
      // Ejemplo: /es/about?foo=bar
      const pathWithLocale = getLocalizedUrl(`${pathname}${search}`, locale);

      // Actualizar la ruta URL
      navigate(pathWithLocale);
    },
  });

  return (
    <div>
      <button popoverTarget="localePopover">{getLocaleName(locale)}</button>
      <div id="localePopover" popover="auto">
        {availableLocales.map((localeItem) => (
          <a
            href={getLocalizedUrl(location.pathname, localeItem)}
            hrefLang={localeItem}
            aria-current={locale === localeItem ? "page" : undefined}
            onClick={(e) => {
              e.preventDefault();
              setLocale(localeItem);
            }}
            key={localeItem}
          >
            <span>
              {/* Local - por ejemplo, FR */}
              {localeItem}
            </span>
            <span>
              {/* Idioma en su propio local - por ejemplo, Français */}
              {getLocaleName(localeItem, locale)}
            </span>
            <span dir={getHTMLTextDir(localeItem)} lang={localeItem}>
              {/* Idioma en el local actual - por ejemplo, Francés con el local actual configurado en Locales.SPANISH */}
              {getLocaleName(localeItem)}
            </span>
            <span dir="ltr" lang={Locales.ENGLISH}>
              {/* Idioma en inglés - por ejemplo, French */}
              {getLocaleName(localeItem, Locales.ENGLISH)}
            </span>
          </a>
        ))}
      </div>
    </div>
  );
};

Referencias de documentación:

useLocale hook

getLocaleName hook

getLocalizedUrl hook

getHTMLTextDir hook

atributo hrefLang

atributo lang

atributo dir

atributo aria-current

Cuando tu aplicación soporta múltiples idiomas, es crucial actualizar los atributos lang y dir de la etiqueta <html> para que coincidan con la configuración regional actual. Hacer esto garantiza:

Accesibilidad: Los lectores de pantalla y las tecnologías de asistencia dependen del atributo lang correcto para pronunciar e interpretar el contenido con precisión.
Renderizado de texto: El atributo dir (dirección) asegura que el texto se muestre en el orden adecuado (por ejemplo, de izquierda a derecha para inglés, de derecha a izquierda para árabe o hebreo), lo cual es esencial para la legibilidad.
SEO: Los motores de búsqueda utilizan el atributo lang para determinar el idioma de tu página, ayudando a mostrar el contenido localizado correcto en los resultados de búsqueda.

Al actualizar estos atributos dinámicamente cuando cambia la configuración regional, garantizas una experiencia coherente y accesible para los usuarios en todos los idiomas soportados.

Implementación del Hook

Crea un hook personalizado para gestionar los atributos HTML. El hook escucha los cambios de local y actualiza los atributos en consecuencia:

import { useEffect } from "react";
import { useLocale } from "react-intlayer";
import { getHTMLTextDir } from "intlayer";

/**
 * Actualiza los atributos `lang` y `dir` del elemento HTML <html> según el local actual.
 * - `lang`: Informa a los navegadores y motores de búsqueda del idioma de la página.
 * - `dir`: Asegura el orden correcto de lectura (por ejemplo, 'ltr' para inglés, 'rtl' para árabe).
 *
 * Esta actualización dinámica es esencial para un renderizado correcto del texto, accesibilidad y SEO.
 */
export const useI18nHTMLAttributes = () => {
  const { locale } = useLocale();

  useEffect(() => {
    // Actualizar el atributo de idioma al local actual.
    document.documentElement.lang = locale;

    // Establecer la dirección del texto basada en el local actual.
    document.documentElement.dir = getHTMLTextDir(locale);
  }, [locale]);
};

Usando el Hook en tu aplicación

Integra el hook en tu componente principal para que los atributos HTML se actualicen cada vez que cambie el local:

import type { FC } from "react";
import { IntlayerProvider, useIntlayer } from "react-intlayer";
import { useI18nHTMLAttributes } from "./hooks/useI18nHTMLAttributes";
import "./App.css";

const AppContent: FC = () => {
  // Aplicar el hook para actualizar los atributos lang y dir de la etiqueta <html> basado en el local.
  useI18nHTMLAttributes();

  // ... Resto de tu componente
};

const App: FC = () => (
  <IntlayerProvider>
    <AppContent />
  </IntlayerProvider>
);

export default App;

Al aplicar estos cambios, tu aplicación:

Garantizará que el atributo idioma (lang) refleje correctamente el local actual, lo cual es importante para SEO y el comportamiento del navegador.
Ajustará la dirección del texto (dir) según el local, mejorando la legibilidad y usabilidad para idiomas con diferentes órdenes de lectura.
Proporcionará una experiencia más accesible, ya que las tecnologías asistivas dependen de estos atributos para funcionar de manera óptima.

Configurar TypeScript

Intlayer utiliza la ampliación de módulos para obtener beneficios de TypeScript y fortalecer tu base de código.

Asegúrate de que tu configuración de TypeScript incluya los tipos autogenerados.

{
  // ... Tus configuraciones existentes de TypeScript
  "include": [
    // ... Tus configuraciones existentes de TypeScript
    ".intlayer/**/*.ts", // Incluir los tipos autogenerados
  ],
}

Configuración de Git

Se recomienda ignorar los archivos generados por Intlayer. Esto te permite evitar comprometerlos en tu repositorio Git.

Para ello, puedes agregar las siguientes instrucciones a tu archivo .gitignore:

# Ignorar los archivos generados por Intlayer
.intlayer

Extensión para VS Code

Para mejorar tu experiencia de desarrollo con Intlayer, puedes instalar la extensión oficial Intlayer VS Code Extension. Instalar desde el Marketplace de VS Code

Esta extensión proporciona:

Autocompletado para las claves de traducción.
Detección de errores en tiempo real para traducciones faltantes.
Previsualizaciones en línea del contenido traducido.
Acciones rápidas para crear y actualizar traducciones fácilmente.

Para más detalles sobre cómo usar la extensión, consulta la documentación de la extensión Intlayer para VS Code.

Ir más allá

Para ir más allá, puedes implementar el editor visual o externalizar tu contenido usando el CMS.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Traduce tu Create React App con Intlayer | Internacionalización (i18n)

¿Qué es Intlayer?

Guía paso a paso para configurar Intlayer en una aplicación React

Implementación del Hook

Usando el Hook en tu aplicación

Configurar TypeScript

Configuración de Git

Extensión para VS Code

Ir más allá

Uh oh!

FilesExpand file tree

intlayer_with_create_react_app.md

Latest commit

History

intlayer_with_create_react_app.md

File metadata and controls

Traduce tu Create React App con Intlayer | Internacionalización (i18n)

¿Qué es Intlayer?

Guía paso a paso para configurar Intlayer en una aplicación React

Implementación del Hook

Usando el Hook en tu aplicación

Configurar TypeScript

Configuración de Git

Extensión para VS Code

Ir más allá