Buenas prácticas

Estas prácticas se basan en patrones que ofrecen resultados fiables y rentables con el Compiler de Lingo.dev. Abarcan el pipeline de compilación, la organización del código, la calidad de la traducción y las pruebas.

Pipeline de compilación#

Usa la estrategia de tres modos#

{
  buildMode: "translate",
  dev: { usePseudotranslator: true },
}

LINGO_BUILD_MODE=translate npm run build

LINGO_BUILD_MODE=cache-only npm run build

Control de versiones#

Haz commit de .lingo/ en tu repositorio#

El archivo .lingo/metadata.json es la fuente de referencia de todas las traducciones en caché. Las compilaciones de producción en modo cache-only dependen de él.

# .gitignore - do NOT ignore .lingo/
node_modules/
dist/
.env

Revisa los diffs de traducción#

Cuando CI haga commit de traducciones actualizadas, revisa el diff de .lingo/metadata.json en las pull requests. Así podrás detectar problemas de traducción antes de que lleguen a producción, igual que harías al revisar cambios de código.

Organización del código#

Coloca el texto traducible directamente en JSX#

El compilador analiza JSX en busca de contenido traducible. El texto almacenado en variables de JavaScript, constantes o archivos externos no se detecta:

// Good - compiler detects this text
export function Header() {
  return <h1>Welcome to our app</h1>;
}

// Bad - compiler cannot detect text in a variable
const title = "Welcome to our app";
export function Header() {
  return <h1>{title}</h1>;
}

Usa useDirective en bases de código grandes#

En proyectos grandes, analizar todos los archivos aumenta el tiempo de compilación. Activa useDirective: true y añade 'use i18n' solo en los archivos que contienen texto visible para el usuario:

{
  useDirective: true,
}

'use i18n';

// Only this file is scanned for translations
export function PublicPage() {
  return <h1>Welcome</h1>;
}

Mantén sourceRoot lo más acotado posible#

Configura sourceRoot con el directorio más pequeño que contenga tus componentes traducibles. Un sourceRoot demasiado amplio analiza archivos innecesarios:

Calidad de la traducción#

Usa overrides manuales para los términos de marca#

Los nombres de marca, los nombres de producto y los textos legales deben usar manual overrides en lugar de depender de la traducción por IA:

<h1 data-lingo-override={{ es: "Motor de Localizacion", de: "Lokalisierungs-Engine" }}>
  Localization Engine
</h1>

Usa el mapeo por pares de idiomas para optimizar costes#

Los distintos modelos ofrecen fortalezas y precios diferentes. Asigna los modelos más caros a los idiomas que realmente los necesiten y usa modelos más rentables en el resto:

{
  models: {
    "*:*": "groq:llama-3.3-70b-versatile",      // Fast, cost-effective default
    "*:ja": "anthropic:claude-3-5-sonnet",       // Higher quality for Japanese
    "*:zh-Hans": "anthropic:claude-3-5-sonnet",  // Higher quality for Chinese
  },
}

Usa el motor de Lingo.dev para el glosario y la voz de marca#

Cuando necesites una terminología coherente en toda tu aplicación, configura un motor de localización en Lingo.dev con un glossary y una voz de marca. Se aplicarán automáticamente a cada solicitud de traducción.

Pluralización#

Desactiva la pluralización si no la necesitas#

Si tu aplicación no muestra cantidades numéricas junto al texto, desactiva la pluralización para reducir la complejidad de la compilación:

{
  pluralization: { enabled: false },
}

Redacta con naturalidad los textos que dependen del recuento#

Cuando la pluralización esté activada, redacta con naturalidad los textos con variables numéricas. El compilador se encarga de la conversión a ICU MessageFormat:

// Good - the compiler detects and pluralizes this
<p>You have {count} items in your cart</p>

// Also good - works with any numeric expression
<p>{unreadCount} unread messages</p>

Pruebas#

Prueba primero con pseudotranslator#

Antes de generar traducciones reales, ejecuta con pseudotranslator para verificar que la cobertura sea completa:

1. Activa dev.usePseudotranslator: true
2. Recorre cada página y componente
3. Cualquier texto sin los marcadores [!!! ... !!!] no se está traduciendo
4. Corrige los problemas de ubicación del texto (mueve el texto a JSX, ajusta sourceRoot y añade directivas 'use i18n')

Prueba con traducciones reales antes del lanzamiento#

Desactiva pseudotranslator y genera traducciones reales para al menos un idioma de destino antes de lanzar:

{
  dev: { usePseudotranslator: false },
}

Comprueba si hay desbordamientos de diseño, truncamientos de texto y problemas con texto bidireccional que las pseudotraducciones no pueden revelar.

Siguientes pasos#