Inicio rápido para The Epic Stack

Cómo configurar Lingo.dev Compiler con The Epic Stack

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 The Epic Stack, un framework de aplicación web full-stack de Kent C. Dodds que está construido sobre Remix.

Lo que aprenderás

  • Cómo inicializar Lingo.dev Compiler en The Epic Stack
  • Cómo configurar el compilador para que sea compatible con The Epic Stack
  • 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 Proyectos.

  3. Haz clic en Clave API > Copiar.

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

    export LINGODOTDEV_API_KEY="<tu_clave_api>"

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 The Epic Stack, 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. Combina la configuración del compilador con la configuración existente y expórtala:

    export default defineConfig((config) => {
  const configWithSentry = {
    ...viteConfig,
    plugins: [
      ...viteConfig.plugins!.filter(Boolean),
      MODE === "production" && process.env.SENTRY_AUTH_TOKEN
        ? sentryReactRouter(sentryConfig, config)
        : null,
    ].filter(Boolean),
  };

  return withLingo(configWithSentry);
});

Con esta configuración implementada, Lingo.dev Compiler:

  • Recorrerá el árbol de sintaxis abstracta (AST) del código base
  • 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:

    const lingoDictionary = await loadDictionary(request);

  3. Devuelve el diccionario como parte de los datos del loader:

    return data(
  {
    user,
    requestInfo: {
      hints: getHints(request),
      origin: getDomainUrl(request),
      path: new URL(request.url).pathname,
      userPrefs: {
        theme: getTheme(request),
      },
    },
    ENV: getEnv(),
    toast,
    honeyProps,
    lingoDictionary,
  },
  {
    headers: combineHeaders(
      { "Server-Timing": timings.toString() },
      toastHeaders,
    ),
  },
);

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 | null>();

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

    <LingoProvider>{/* Código existente de la aplicación */}</LingoProvider>

  4. Pasa el diccionario cargado al componente:

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

Paso 5. Configurar un selector de locale

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

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

Para utilizar el componente, intégralo en cualquier parte de tu aplicación y establece la propiedad locales como un array que contenga los locales 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 una interfaz de usuario personalizadas para cambiar 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 Lingo.dev Compiler se ha configurado correctamente:

  1. Inicia el servidor de desarrollo:

    npm run dev

  2. Navega a localhost:3000.

  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 funciona 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