Mejores prácticas

Estas prácticas se basan en patrones que ofrecen resultados confiables 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 verdad 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 los pull requests. Así podrás detectar problemas de traducción antes de que lleguen a producción, igual que revisas los cambios de código.

Organización del código#

Coloca el texto traducible directamente en JSX#

El Compiler 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 agrega '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 hace que se analicen archivos innecesarios:

Calidad de la traducción#

Usa manual overrides para términos de marca#

Los nombres de marca, los nombres de productos y el texto legal deben usar manual overrides en lugar de depender de la traducción con IA:

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

Usa el mapeo por pares de idioma para optimizar costos#

Los distintos modelos tienen fortalezas y precios diferentes. Asigna los modelos más costosos a los idiomas que realmente los necesitan 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 glossary y voz de marca#

Cuando necesites terminología consistente en toda tu app, configura un motor de localización en Lingo.dev con un glossary y una voz de marca. Ambos se aplican automáticamente a cada solicitud de traducción.

Pluralización#

Desactiva la pluralización si no la necesitas#

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

{
  pluralization: { enabled: false },
}

Escribe de forma natural el texto que depende de cantidades#

Cuando la pluralización esté activada, redacta de forma natural el texto con variables numéricas. El Compiler se encarga de convertirlo 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 el pseudotranslator para verificar que la cobertura sea completa:

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

Prueba con traducciones reales antes del lanzamiento#

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

{
  dev: { usePseudotranslator: false },
}

Verifica desbordes de diseño, truncamiento de texto y problemas con texto bidireccional que las pseudotraducciones no pueden mostrar.

Siguientes pasos#