Comenzando con la internacionalización (i18n) usando Intlayer y React Native

Consulta la Plantilla de Aplicación en GitHub.

¿Qué es Intlayer?

Intlayer es una biblioteca innovadora y de código abierto para la internacionalización (i18n) que simplifica el soporte multilingüe en aplicaciones modernas. Funciona en muchos entornos de JavaScript/TypeScript, incluyendo React Native (a través del paquete react-intlayer).

Con Intlayer, puedes:

• Gestionar fácilmente las traducciones usando diccionarios declarativos a nivel de componente.
• Garantizar soporte para TypeScript con tipos autogenerados.
• Localizar dinámicamente contenido, incluyendo cadenas de la interfaz de usuario (y en React para web, también puede localizar metadatos HTML, etc.).
• Beneficiarte de funciones avanzadas, como la detección y cambio dinámico de la configuración regional.

Paso 1: Instalar dependencias

Desde tu proyecto React Native, instala los siguientes paquetes:

npm install intlayer react-intlayernpm install --save-dev react-native-intlayer

Paquetes

• intlayer
  El conjunto de herramientas principal de i18n para configuración, contenido de diccionarios, generación de tipos y comandos CLI.

• react-intlayer
  Integración con React que proporciona los proveedores de contexto y hooks de React que usarás en React Native para obtener y cambiar configuraciones regionales.

• react-native-intlayer
  Integración con React Native que proporciona el plugin Metro para integrar Intlayer con el empaquetador de React Native.

Paso 2: Crear una Configuración de Intlayer

En la raíz de tu proyecto (o en cualquier lugar conveniente), crea un archivo de configuración de Intlayer. Podría verse así:

/** * Si los tipos de Locales no están disponibles, intenta configurar moduleResolution a "bundler" en tu tsconfig.json */import { Locales, type IntlayerConfig } from "intlayer";const config: IntlayerConfig = {  internationalization: {    locales: [      Locales.ENGLISH,      Locales.FRENCH,      Locales.SPANISH,      // ... Agrega cualquier otra configuración regional que necesites    ],    defaultLocale: Locales.ENGLISH,  },};export default config;

Dentro de esta configuración, puedes:

• Configurar tu lista de configuraciones regionales soportadas.
• Establecer una configuración regional predeterminada.
• Más adelante, puedes agregar opciones más avanzadas (por ejemplo, registros, directorios de contenido personalizados, etc.).
• Consulta la documentación de configuración de Intlayer para más información.

Paso 3: Añadir el plugin de Metro

Metro es un empaquetador para React Native. Es el empaquetador predeterminado para proyectos de React Native creados con el comando react-native init. Para usar Intlayer con Metro, necesitas añadir el plugin en tu archivo metro.config.js:

const { getDefaultConfig } = require("expo/metro-config");const { configMetroIntlayer } = require("react-native-intlayer/metro");module.exports = (async () => {  const defaultConfig = getDefaultConfig(__dirname);  return await configMetroIntlayer(defaultConfig);})();

Paso 4: Añadir el proveedor de Intlayer

Para mantener sincronizado el idioma del usuario en toda tu aplicación, necesitas envolver tu componente raíz con el componente IntlayerProvider de react-intlayer.

Además, debes añadir la función intlayerPolyfill a tu archivo index.js para asegurar que Intlayer funcione correctamente.

import { Stack } from "expo-router";import { getLocales } from "expo-localization";import { IntlayerProviderContent } from "react-intlayer";import { intlayerPolyfill } from "react-native-intlayer";import { type FC } from "react";intlayerPolyfill();const getDeviceLocale = () => getLocales()[0]?.languageTag;const RootLayout: FC = () => {  return (    <IntlayerProviderContent defaultLocale={getDeviceLocale()}>      <Stack>        <Stack.Screen name="(tabs)" options={{ headerShown: false }} />      </Stack>    </IntlayerProviderContent>  );};export default RootLayout;

Paso 5: Declara Tu Contenido

Crea archivos de declaración de contenido en cualquier lugar de tu proyecto (comúnmente dentro de src/), usando cualquiera de los formatos de extensión que Intlayer soporta:

• .content.json
• .content.ts
• .content.tsx
• .content.js
• .content.jsx
• .content.mjs
• .content.mjx
• .content.cjs
• .content.cjx
• etc.

Ejemplo (TypeScript con nodos TSX para React Native):

import { t, type Dictionary } from "intlayer";import type { ReactNode } from "react";/** * Diccionario de contenido para nuestro dominio "app" */import { t, type Dictionary } from "intlayer";const homeScreenContent = {  key: "home-screen",  content: {    title: t({      en: "Welcome!",      fr: "Bienvenue!",      es: "¡Bienvenido!",    }),  },} satisfies Dictionary;export default homeScreenContent;

Para más detalles sobre las declaraciones de contenido, consulta la documentación de contenido de Intlayer.

Paso 4: Usa Intlayer en tus Componentes

Usa el hook useIntlayer en componentes hijos para obtener contenido localizado.

Ejemplo

import { Image, StyleSheet, Platform } from "react-native";import { useIntlayer } from "intlayer";import { HelloWave } from "@/components/HelloWave";import ParallaxScrollView from "@/components/ParallaxScrollView";import { ThemedText } from "@/components/ThemedText";import { ThemedView } from "@/components/ThemedView";import { type FC } from "react";const HomeScreen = (): FC => {  const { title, steps } = useIntlayer("home-screen");  return (    <ParallaxScrollView      headerBackgroundColor={{ light: "#A1CEDC", dark: "#1D3D47" }}      headerImage={        <Image          source={require("@/assets/images/partial-react-logo.png")}          style={styles.reactLogo}        />      }    >      <ThemedView style={styles.titleContainer}>        <ThemedText type="title">{title}</ThemedText>        <HelloWave />      </ThemedView>    </ParallaxScrollView>  );};const styles = StyleSheet.create({  titleContainer: {    flexDirection: "row",    alignItems: "center",    gap: 8,  },});export default HomeScreen;

Al usar content.someKey en propiedades basadas en cadenas (por ejemplo, el title de un botón o los children de un componente Text), llama a content.someKey.value para obtener la cadena real.

(Opcional) Paso 5: Cambiar la configuración regional de la aplicación

Para cambiar la configuración regional desde dentro de tus componentes, puedes usar el método setLocale del hook useLocale:

import { type FC } from "react";import { View, Text, TouchableOpacity, StyleSheet } from "react-native";import { getLocaleName } from "intlayer";import { useLocale } from "react-intlayer";export const LocaleSwitcher: FC = () => {  const { setLocale, availableLocales } = useLocale();  return (    <View style={styles.container}>      {availableLocales.map((locale) => (        <TouchableOpacity          key={locale}          style={styles.button}          onPress={() => setLocale(locale)}        >          <Text style={styles.text}>{getLocaleName(locale)}</Text>        </TouchableOpacity>      ))}    </View>  );};const styles = StyleSheet.create({  container: {    flexDirection: "row",    justifyContent: "center",    alignItems: "center",    gap: 8,  },  button: {    paddingVertical: 6,    paddingHorizontal: 12,    borderRadius: 6,    backgroundColor: "#ddd",  },  text: {    fontSize: 14,    fontWeight: "500",    color: "#333",  },});

Esto provoca una nueva renderización de todos los componentes que usan contenido de Intlayer, mostrando ahora las traducciones para la nueva configuración regional.

Consulta la documentación de useLocale para más detalles.

Configurar TypeScript (si usas TypeScript)

Intlayer genera definiciones de tipos en una carpeta oculta (por defecto .intlayer) para mejorar la autocompletación y detectar errores de traducción:

// tsconfig.json{  // ... tu configuración TS existente  "include": [    "src", // tu código fuente    ".intlayer/types/**/*.ts", // <-- asegura que se incluyan los tipos generados automáticamente    // ... cualquier otra cosa que ya incluyas  ],}

Esto habilita características como:

• Autocompletado para las claves de tu diccionario.
• Verificación de tipos que avisa si accedes a una clave inexistente o si hay un desajuste de tipo.

Configuración de Git

Para evitar comprometer archivos generados automáticamente por Intlayer, añade lo siguiente a tu .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 de Intlayer para VS Code.

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á

• Editor Visual: Usa el Editor Visual de Intlayer para gestionar las traducciones visualmente.
• Integración con CMS: También puedes externalizar y obtener el contenido de tu diccionario desde un CMS.
• Comandos CLI: Explora el CLI de Intlayer para tareas como extraer traducciones o verificar claves faltantes.

¡Disfruta construyendo tus aplicaciones React Native con i18n completamente potenciado a través de Intlayer!

Historial del Documento

• 5.5.10 - 2025-06-29: Historial inicial