Traduce tu aplicación Expo y React Native | Internacionalización (i18n)

Tabla de Contenidos

¿Por qué Intlayer en lugar de alternativas?

En comparación con soluciones principales como react-native-localize o i18next, Intlayer es una solución que viene con optimizaciones integradas como:

1. 1

   Instalar dependencias

   Consulte Plantilla de aplicación en GitHub.

   Desde su proyecto React Native, instale los siguientes paquetes:

   bash

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   npx intlayer init --interactive
   

   La bandera --interactive es opcional. Usa intlayer-cli init si eres un agente de IA.

   Este comando detectará su entorno e instalará los paquetes necesarios. Por ejemplo:

   bash

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   npm install intlayer 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-native-intlayer
     Integración con React Native que proporciona los proveedores de contexto y hooks de React que usarás para obtener y cambiar configuraciones regionales, los polyfills de React Native y el plugin Metro para integrar Intlayer con el empaquetador de React Native. Re-exporta todo desde react-intlayer, por lo que solo necesitas este único paquete en una aplicación React Native.

2. 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í:

   intlayer.config.ts

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   /**
    * 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.
3. 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:

   metro.config.js

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

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

   Nota: configMetroIntlayer es una función asíncrona. Usa configMetroIntlayerSync en su lugar si deseas usarlo de forma síncrona, o evitar IIFE (Expresión de función invocada inmediatamente). Nota: configMetroIntlayerSync no permite construir diccionarios de intlayer al iniciar el servidor

4. 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-native-intlayer.

   Importa siempre desde react-native-intlayer. Su IntlayerProvider incluye polyfills para la API web usada por Intlayer, y el paquete re-exporta todos los hooks y utilidades de react-intlayer.

   Además, necesitas agregar la función intlayerPolyfill a tu archivo index.js para garantizar que Intlayer pueda funcionar correctamente.

   app/_layout.tsx

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

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

5. 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.jsonc
   • .content.json5
   • .content.ts
   • .content.tsx
   • .content.js
   • .content.jsx
   • .content.mjs
   • .content.mjx
   • .content.cjs
   • .content.md
   • .content.mdx
   • .content.yaml
   • .content.yml
   • etc.

   Expo Router (web): mantén los archivos .content.* fuera del directorio app/. Expo Router trata cada archivo JavaScript/TypeScript dentro de app/ como una ruta. En la web, su descubrimiento de rutas escanea el sistema de archivos directamente y no respeta el resolver.blockList de Metro, por lo que un *.content.ts co-ubicado se registra como una ruta. Un archivo como app/(tabs)/_layout.content.ts incluso se analiza como un diseño (la parte .content se lee como un sufijo de plataforma), lo que choca con el _layout.tsx real y lanza:

   plaintext

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   The layouts "./(tabs)/_layout.content.ts" and "./(tabs)/_layout.tsx" conflict on the route "/(tabs)/_layout.content". Remove or rename one of these files.
   

   Coloca tus declaraciones en un directorio fuera de app/ (por ejemplo, content/ o src/content/). Intlayer descubre los archivos .content.* en cualquier lugar del proyecto y los diccionarios se referencian por su key, por lo que no se necesitan cambios en las importaciones. En nativo esto no es necesario (el blockList de Metro ya los oculta), pero usar un directorio distinto de app/ mantiene ambas plataformas funcionando.

   Ejemplo (TypeScript con nodos TSX para React Native):

   src/app.content.tsx

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   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.

6. 6

   Usa Intlayer en tus Componentes

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

   Ejemplo

   app/(tabs)/index.tsx

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { Image, StyleSheet, Platform } from "react-native";
   import { useIntlayer } from "react-native-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.

   Si su aplicación ya existe, puede utilizar el Compilador Intlayer, así como el comando de extracción, para transformar miles de componentes en un segundo.

7. 7

   Cambiar la configuración regional de la aplicación

   Opcional

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

   src/components/LocaleSwitcher.tsx

   Copiar contenido

   Copiar código

   Copiar el código al portapapeles

   import { type FC } from "react";
   import { View, Text, TouchableOpacity, StyleSheet } from "react-native";
   import { getLocaleName } from "intlayer";
   import { useLocale } from "react-native-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!

Debug

React Native puede ser menos estable que React Web, por lo que debes prestar especial atención a la alineación de versiones.

Intlayer se orienta principalmente a la Web Intl API; en React Native debes incluir los polyfills apropiados.

Lista de verificación:

• Usa las últimas versiones de intlayer y react-native-intlayer.
• Habilita el polyfill de Intlayer.
• Si usas getLocaleName u otras utilidades basadas en Intl-API, importa estos polyfills temprano (por ejemplo en index.js o App.tsx):

import "intl";
import "@formatjs/intl-getcanonicallocales/polyfill";
import "@formatjs/intl-locale/polyfill";
import "@formatjs/intl-pluralrules/polyfill";
import "@formatjs/intl-displaynames/polyfill";
import "@formatjs/intl-listformat/polyfill";
import "@formatjs/intl-numberformat/polyfill";
import "@formatjs/intl-relativetimeformat/polyfill";
import "@formatjs/intl-datetimeformat/polyfill";

• Verifica tu configuración de Metro (resolver aliases, asset plugins, rutas de tsconfig) si los módulos no se resuelven.

Preguntas frecuentes