Inicio rápido para React Router (v7)

Cómo configurar Lingo.dev Compiler con React Router (v7)

Introducción

Lingo.dev Compiler es una herramienta potenciada por IA que te permite localizar aplicaciones basadas en React sin realizar cambios en los componentes existentes. Solo configuras algunas cosas, envuelves tu aplicación en un proveedor de contexto, y eso es todo — tu aplicación está localizada.

Esta guía explica cómo configurar Lingo.dev Compiler con la v7 de React Router, un framework React de pila completa. Si estás usando la v6, consulta Inicio rápido para React Router (v6).

Lo que aprenderás

  • Cómo inicializar Lingo.dev Compiler en React Router
  • Cómo configurar el compilador para que sea compatible con React Router
  • Cómo configurar un selector de idioma para cambiar entre locales

Paso 1. Configura una clave API

Lingo.dev Compiler utiliza modelos de lenguaje de gran escala (LLMs) para localizar aplicaciones con IA. Para usar uno de estos modelos, necesitas una clave API de un proveedor compatible.

Para comenzar lo más rápido posible, recomendamos usar Lingo.dev Engine — nuestra propia plataforma alojada que ofrece 10,000 tokens de uso mensual gratuito.

Para configurar una clave API:

  1. Inicia sesión en Lingo.dev Engine.

  2. Navega a la página de Projects.

  3. Haz clic en API key > Copy.

  4. Almacena la clave API en una variable de entorno:

    export LINGODOTDEV_API_KEY="<your_api_key>"

Alternativa: Proveedores LLM personalizados

No tienes que usar Lingo.dev Engine. Puedes configurar el compilador para integrarlo con varios proveedores LLM personalizados, incluyendo:

  • Groq
  • Google
  • Mistral
  • Ollama
  • OpenRouter

Paso 2. Instala el paquete

Lingo.dev Compiler se distribuye como parte del paquete npm lingo.dev. Para instalarlo, usa tu gestor de paquetes preferido:

npm install lingo.dev

Paso 3. Inicializar el compilador

Lingo.dev Compiler se integra con Vite y se ejecuta durante el tiempo de compilación. Para conectarse al proceso de compilación de Vite, realiza los siguientes cambios en el archivo vite.config.ts:

  1. Importa el compilador:

    import lingoCompiler from "lingo.dev/compiler";

  2. Inicializa el compilador con el método vite:

    const withLingo = lingoCompiler.vite({
  sourceRoot: "app",
  lingoDir: "lingo",
  sourceLocale: "en",
  targetLocales: ["es"],
  rsc: false,
  useDirective: false,
  debug: false,
  models: "lingo.dev",
});

    Para compatibilidad con React Router, asegúrate de que:

    • sourceRoot esté configurado como "app"
    • rsc esté configurado como false

    Para obtener más información sobre las opciones disponibles, consulta Opciones del compilador.

  3. Envuelve tu configuración existente de Vite con el compilador:

    const viteConfig: UserConfig = {
  plugins: [tailwindcss(), reactRouter(), tsconfigPaths()],
};

export default withLingo(viteConfig);

Con esta configuración en su lugar, Lingo.dev Compiler:

  • Recorrerá el árbol de sintaxis abstracta (AST) de la base de código
  • Encontrará contenido localizable (es decir, texto en elementos JSX y ciertos valores de atributos)
  • Utilizará el/los modelo(s) de IA configurado(s) para generar traducciones
  • Almacenará el contenido original y traducido en un archivo dictionary.js
  • Reemplazará el contenido localizado con marcadores de posición

Paso 4. Cargar el contenido localizado

Después de que el compilador procese tu aplicación y genere traducciones, necesitas cargar y servir este contenido localizado a tus usuarios. Esto implica:

  • Cargar el diccionario apropiado basado en la preferencia de idioma del usuario
  • Proporcionar las traducciones cargadas a tu aplicación a través de un proveedor de contexto

Cargando el diccionario

En el archivo app/root.tsx:

  1. Importa la función loadDictionary desde lingo.dev/react/react-router:

    import { loadDictionary } from "lingo.dev/react/react-router";

    Esta función:

    • Recupera el locale actual desde la cookie lingo-locale
    • Utiliza "en" como valor predeterminado cuando no se define un locale
    • Carga el contenido localizado desde el archivo dictionary.js

  2. Llama a la función loadDictionary desde la función loader:

    export async function loader({ request }: Route.LoaderArgs) {
  const lingoDictionary = await loadDictionary(request);
  return {
    lingoDictionary,
  };
}

Proporcionando las traducciones

En el archivo app/root.tsx:

  1. Importa el componente LingoProvider desde lingo.dev/react/client:

    import { LingoProvider } from "lingo.dev/react/client";

    Este componente es un proveedor de contexto de React que reemplaza los marcadores de posición creados por el compilador con el contenido localizado.

  2. En el componente Layout, obtén los datos del cargador de datos:

    const data = useLoaderData<typeof loader>();

  3. Envuelve la aplicación en el componente LingoProvider:

    <LingoProvider dictionary={data?.lingoDictionary}>
  {/* Código existente de la aplicación */}
</LingoProvider>

Paso 5. Configurar un selector de idioma

Para permitir que los usuarios cambien entre idiomas, importa el LocaleSwitcher desde el paquete lingo.dev. Este es un componente sin estilos que:

  • Renderiza un desplegable de idiomas disponibles
  • Permite a los usuarios seleccionar un idioma
  • Recuerda el idioma seleccionado para futuras visitas

Para usar el componente, intégralo en cualquier parte de tu aplicación y establece la propiedad locales como un array que contenga los idiomas de origen y destino configurados:

import { LocaleSwitcher } from "lingo.dev/react/client";

<LocaleSwitcher locales={["en", "es"]} />;

Alternativa: Selector de idioma personalizado

No es obligatorio usar el componente LocaleSwitcher. Puedes implementar una lógica y UI personalizadas para el cambio de idioma. El único requisito es leer y escribir el idioma activo en la cookie lingo-locale.

Paso 6. Ejecutar la aplicación

Para verificar que el Compilador de Lingo.dev se ha configurado correctamente:

  1. Inicia el servidor de desarrollo:

    npm run dev

  2. Navega a localhost:5173.

  3. Utiliza el componente LocaleSwitcher para cambiar entre idiomas.

La página debería recargarse y mostrar el contenido localizado.

Alternativa: Configurar cookies manualmente

Si no estás utilizando el componente LocaleSwitcher, una forma alternativa de verificar que la localización está funcionando es configurando manualmente la cookie lingo-locale.

Si estás usando Google Chrome, sigue estas instrucciones:

  1. Navega a Ver > Desarrollador > Herramientas para desarrolladores.
  2. Ve a la pestaña Aplicación.
  3. En la barra lateral izquierda, bajo Almacenamiento, expande Cookies y selecciona la URL del sitio.
  4. En la tabla de cookies, haz clic derecho en cualquier lugar y selecciona Añadir.
  5. En la columna Nombre, introduce lingo-locale.
  6. En la columna Valor, introduce el idioma deseado (por ejemplo, es).
  7. Presiona Enter para guardar la cookie.
  8. Actualiza la página para aplicar la cookie.

Lecturas adicionales