Solución de problemas

Problemas comunes y soluciones al usar @lingo.dev/compiler.

Problemas de instalación

"Cannot find module '@lingo.dev/compiler'"

Causa: el paquete no está instalado o se instaló incorrectamente.

Solución:

npm install @lingo.dev/compiler
# or
pnpm install @lingo.dev/compiler

Verifica la instalación:

ls node_modules/@lingo.dev/compiler

"Module not found: Can't resolve '@lingo.dev/compiler/react'"

Causa: importación desde una ruta incorrecta o paquete desactualizado.

Solución:

  1. Verifica la declaración de importación:

    import { LingoProvider } from "@lingo.dev/compiler/react"; // Correct

  2. Reinstala el paquete:

    rm -rf node_modules
npm install

Problemas de configuración

"Config must be async function" (Next.js)

Causa: la configuración de Next.js no está envuelta en una función asíncrona.

Solución:

// Wrong
export default withLingo(nextConfig, {...});

// Correct
export default async function (): Promise<NextConfig> {
  return await withLingo(nextConfig, {...});
}

"sourceLocale is required"

Causa: falta sourceLocale en la configuración.

Solución:

{
  sourceLocale: "en", // Required
  targetLocales: ["es", "de"],
}

"targetLocales must be an array"

Causa: targetLocales no es un array o está vacío.

Solución:

{
  targetLocales: ["es", "de"], // Must be array with at least one locale
}

Problemas de traducción

Las traducciones no se muestran

Síntomas: el texto aparece solo en el idioma de origen.

Causas y soluciones:

1. LingoProvider no añadido o en ubicación incorrecta

// Wrong - too low in tree
export default function Page() {
  return (
    <LingoProvider>
      <Content />
    </LingoProvider>
  );
}

// Correct - in root layout
export default function RootLayout({ children }) {
  return (
    <LingoProvider>
      <html>
        <body>{children}</body>
      </html>
    </LingoProvider>
  );
}

2. Traducciones faltantes en los metadatos Verifica .lingo/metadata.json:

{
  "translations": {
    "abc123": {
      "locales": {
        "es": "..." // Should have translation
      }
    }
  }
}

Si está vacío o falta, ejecuta con buildMode: "translate":

npm run dev # or build

3. El modo de compilación es cache-only sin traducciones en caché

# Generate translations first
LINGO_BUILD_MODE=translate npm run build

# Then use cache-only
LINGO_BUILD_MODE=cache-only npm run build

Todas las traducciones son "[!!! ...]"

Causa: el pseudotraductor está habilitado.

Solución:

{
  dev: {
    usePseudotranslator: false, // Disable for real translations
  }
}

Reinicia el servidor de desarrollo.

Algunos textos no se traducen

Causas:

1. Contenido dinámico o props

// Not translated (yet) - string in variable
const title = "Welcome";
<h1>{title}</h1>

// Translated - string in JSX
<h1>Welcome</h1>

Solución: el compilador se está mejorando para admitir literales de cadena. Por ahora, coloca el texto directamente en JSX.

2. El texto en atributos requiere un manejo específico

// Translated automatically
<img alt="Logo" />
<button aria-label="Close" />

// May need explicit handling
<div custom-attr="Some text" /> // Not translated unless configured

3. useDirective está habilitado Si useDirective: true, los archivos sin 'use i18n' no se traducen.

Solución: Añade la directiva:

'use i18n';

export function Component() { ... }

Problemas de compilación

"Faltan traducciones para el locale X"

Causa: buildMode: "cache-only" pero faltan las traducciones.

Solución:

  1. Genera las traducciones:

    npm run dev # or
LINGO_BUILD_MODE=translate npm run build

  2. Haz commit de .lingo/metadata.json

  3. Reintenta con cache-only

"Error al generar la traducción"

Causas:

1. Clave de API inválida

# Check .env file
cat .env | grep API_KEY

Asegúrate de que la clave de API sea correcta para tu proveedor.

2. Problemas de red Prueba la conexión con la API:

curl https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

3. Limitación de tasa Reduce la velocidad de generación de traducciones o actualiza el nivel de tu API.

4. Configuración de modelo inválida

// Wrong
{
  models: {
    "*:*": "invalid-provider:model",
  }
}

// Correct
{
  models: {
    "*:*": "groq:llama-3.3-70b-versatile",
  }
}

La compilación es lenta

Causas:

1. Generación de muchas traducciones La primera compilación con texto nuevo es lenta. Las compilaciones posteriores son rápidas (en caché).

2. Pseudotranslator deshabilitado en desarrollo

{
  dev: {
    usePseudotranslator: true, // Enable for fast development
  }
}

3. Pluralización habilitada innecesariamente

{
  pluralization: {
    enabled: false, // Disable if not using plural forms
  }
}

Problemas de HMR

HMR no funciona

Causa: Ubicación de LingoProvider o configuración del framework.

Soluciones:

Next.js: Asegúrate de que LingoProvider esté en el layout raíz, no en layouts anidados.

Vite: Asegúrate de que lingoCompilerPlugin esté colocado antes del plugin react():

plugins: [
  lingoCompilerPlugin({...}), // Before react plugin
  react(),
]

El estado se reinicia al cambiar la traducción

Causa: Recarga de página activada por el cambio de locale.

Comportamiento esperado: setLocale() recarga la página por defecto para aplicar el nuevo locale.

Para evitar la recarga: Implementa un persistLocale personalizado sin recarga:

// .lingo/locale-resolver.client.ts
export function persistLocale(locale: string): void {
  localStorage.setItem("locale", locale);
  // Don't call window.location.reload()
}

Nota: Esto requiere precargar las traducciones para todos los locales.

Problemas de API/autenticación

"Clave de API inválida"

Soluciones:

1. Verifica el nombre de la variable de entorno

# Lingo.dev Engine
LINGODOTDEV_API_KEY=...

# OpenAI
OPENAI_API_KEY=sk-...

# Anthropic
ANTHROPIC_API_KEY=sk-ant-...

2. Verifica que la clave de API esté activa Inicia sesión en el panel del proveedor y verifica el estado de la clave.

3. Reinicia el servidor de desarrollo después de agregar la clave

npm run dev

Las variables de entorno se cargan al iniciar.

"Autenticación fallida" (Lingo.dev)

Soluciones:

1. Volver a autenticar

npx lingo.dev@latest login

2. Clave API manual

# Add to .env
LINGODOTDEV_API_KEY=your_key_here

Obtén la clave desde la configuración del proyecto en lingo.dev.

El navegador bloquea el flujo de autenticación

Causa: El navegador Brave o extensiones bloquean la autenticación.

Solución: Añade manualmente la clave API a .env:

LINGODOTDEV_API_KEY=...

Problemas del servidor

"El servidor de traducción no pudo iniciarse"

Causa: Los puertos 60000-60099 están todos en uso.

Soluciones:

1. Configurar un rango de puertos diferente

{
  dev: {
    translationServerStartPort: 61000,
  }
}

2. Finalizar procesos existentes

# Find processes using ports
lsof -i :60000-60099

# Kill process
kill -9 <PID>

"El puerto 60000 ya está en uso"

Causa: Otro proceso está usando ese puerto.

Solución: El servidor encuentra automáticamente el siguiente puerto disponible. Consulta la consola para ver el puerto real:

[lingo] Translation server started on port 60001

Si todos los puertos están ocupados, consulta "El servidor de traducción no pudo iniciarse" más arriba.

Errores de tipo

"Property 'data-lingo-override' does not exist"

Causa: TypeScript no reconoce el atributo.

Solución: Añade la declaración de tipo:

// global.d.ts
declare namespace React {
  interface HTMLAttributes<T> {
    "data-lingo-override"?: Record<string, string>;
  }
}

O usa comillas:

<div {"data-lingo-override"}={{ es: "..." }}>
  Text
</div>

"Type error: Config must return Promise"

Causa: La configuración de Next.js no está correctamente tipada.

Solución:

import type { NextConfig } from "next";
import { withLingo } from "@lingo.dev/compiler/next";

const nextConfig: NextConfig = {};

export default async function (): Promise<NextConfig> {
  return await withLingo(nextConfig, {...});
}

Problemas en producción

Traducciones faltantes en producción

Causas:

1. .lingo/ no está commiteado

git add .lingo/
git commit -m "chore: add translations"
git push

2. El modo de compilación de producción es incorrecto

// Should be cache-only in production
{
  buildMode: "cache-only",
}

3. CI no generó las traducciones Revisa los logs de CI—asegúrate de que las traducciones se generaron y commitearon.

Traducciones diferentes en desarrollo vs producción

Causa: Pseudotraductor habilitado en producción.

Solución:

{
  dev: {
    usePseudotranslator: process.env.NODE_ENV === "development", // Only in dev
  }
}

Obtener ayuda

Si sigues atascado:

  1. Revisa los logs — Busca mensajes de error en la consola
  2. Revisa .lingo/metadata.json — Verifica la estructura y el contenido
  3. Prueba con el pseudotraductor — Aísla problemas de API
  4. Revisa los issues de GitHub — github.com/lingodotdev/lingo.dev/issues
  5. Pregunta en Discord — discord.gg/lingo

Al solicitar ayuda, incluye:

  • Mensaje de error (stack trace completo)
  • Configuración (next.config.ts o vite.config.ts)
  • Versiones de paquetes (npm list @lingo.dev/compiler)
  • Pasos para reproducir

Preguntas frecuentes

P: ¿Necesito claves API en producción? R: No, con buildMode: "cache-only". Las traducciones se generan previamente en CI.

P: ¿Por qué falla mi build? R: Revisa el mensaje de error. Causas comunes: traducciones faltantes, clave API inválida, problemas de red.

P: ¿Puedo usar múltiples proveedores LLM? R: Sí, con mapeo de pares de locales en la configuración de models.

P: ¿Cómo pruebo sin costos de API? R: Habilita usePseudotranslator: true en desarrollo.

Próximos pasos