Internacionalización de Sitios Web
Flujo de trabajo completo para añadir soporte multilingüe a sitios web Next.js con las mejores prácticas de SEO.
Cuándo usar esta habilidad
- Agregar nuevas versiones de idioma a un sitio web existente
- Configurar i18n (internacionalización) para un nuevo sitio web
- Configurar SEO para múltiples idiomas
- El usuario menciona: "agregar idioma", "traducción", "localización", "hreflang", "multilingüe"
Idiomas Soportados
Mercados objetivo comunes:
- 🇺🇸 Inglés (en) - Mercado global
- 🇯🇵 Japonés (ja) - Mercado asiático
- 🇨🇳 Chino (zh) - Mercado chino
Soporte extendido disponible para:
- Coreano (ko), Portugués (pt), Español (es), Francés (fr), Alemán (de)
- Árabe (ar), Vietnamita (vi), Hindi (hi), Indonesio (id), Tailandés (th)
- Chino tradicional (zh-hk), Italiano (it), Ruso (ru)
Flujo de Trabajo de Internacionalización
Copia esta lista de verificación y sigue tu progreso:
Progreso i18n:
- [ ] Paso 1: Preparar archivos base de idioma
- [ ] Paso 2: Agregar nuevos archivos de idioma
- [ ] Paso 3: Actualizar archivos de configuración
- [ ] Paso 4: Agregar traducciones
- [ ] Paso 5: Configurar elementos SEO
- [ ] Paso 6: Validar y probar
Paso 1: Preparar archivos base de idioma
Asegúrate de que los archivos en inglés (en.json) existan como plantillas:
Directorios requeridos:
i18n/messages/en.json- Traducciones principalesi18n/pages/landing/en.json- Traducciones de la página de inicio
Verifica la estructura:
# Comprueba si existen los archivos base
ls i18n/messages/en.json
ls i18n/pages/landing/en.json
Si faltan, créalos con las claves de traducción completas para tu sitio web.
Paso 2: Agregar nuevos archivos de idioma
Ejecuta el script de adición de idiomas:
node scripts/i18n-add-languages.mjs
Qué hace este script:
- Copia
en.jsona todos los archivos de idioma destino - Actualiza
i18n/locale.tscon los nuevos locales - Actualiza
i18n/request.tscon los mapeos de idioma - Actualiza
public/sitemap.xmlcon las nuevas URLs de idioma
Configuración del script (en i18n-add-languages.mjs):
- Array
languages- Lista de idiomas a agregar - Objeto
languageNames- Nombres para mostrar de los idiomas - Array
targetDirs- Directorios que contienen archivos de traducción
Consulta WORKFLOW.md para una guía detallada paso a paso.
Paso 3: Verificar las actualizaciones de configuración
Revisa i18n/locale.ts:
export const locales = ["en", "ja", "zh", "ko", ...];
export const localeNames: any = {
en: "English",
ja: "日本語",
zh: "中文",
ko: "한국어",
...
};
Revisa i18n/request.ts:
- Mapeos de códigos de idioma configurados
- Mapeos
zh-CN→zh,zh-HK→zh-hkpresentes
Revisa public/sitemap.xml:
- Todas las versiones de idioma listadas
- Etiquetas
hreflangpresentes para cada URL
Paso 4: Agregar traducciones
Opción A: Usar traducción con IA (más rápida pero necesita revisión):
# Agrega datos estructurados y traducciones de precios
node scripts/i18n-add-schema.js
Configura las traducciones en el objeto translations del script.
Opción B: Traducción manual (recomendada para calidad):
Edita cada archivo de idioma con las traducciones adecuadas:
# Abre el archivo de idioma
code i18n/messages/ja.json
Mejores prácticas de traducción:
- Usa hablantes nativos cuando sea posible
- Mantén las palabras clave SEO en el idioma de destino
- Adapta el contenido a la cultura local, no solo traduzcas
- Mantén el formato consistente (placeholders, variables)
Consulta reference/locale-codes.md para la referencia de códigos de idioma.
Paso 5: Configurar elementos SEO
Etiquetas hreflang - Automáticas mediante el mapa del sitio, pero verifica:
Consulta reference/hreflang-guide.md para una guía completa.
Metaetiquetas localizadas - Traduce en cada archivo de idioma:
{
"metadata": {
"title": "Título de tu sitio",
"description": "Tu descripción SEO"
}
}
Estructura de URL - Verifica el formato correcto:
- Inglés:
https://example.com/ohttps://example.com/en/ - Japonés:
https://example.com/ja/ - Chino:
https://example.com/zh/
Paso 6: Validar y probar
Construye el proyecto:
npm run build
CRÍTICO: Corrige cualquier error antes de continuar.
Pruebas manuales:
-
Selector de idioma:
- Visita cada versión de idioma
- Verifica que el selector de idioma muestre todos los idiomas
- Haz clic en cada enlace de idioma, verifica que se cargue la página correcta
-
Visualización de contenido:
- Revisa que todas las páginas se rendericen correctamente en cada idioma
- Verifica que no haya texto sin traducir (busca inglés en páginas que no son en inglés)
- Prueba que los caracteres especiales se muestren correctamente (japonés, chino, árabe)
-
Elementos SEO:
- Inspecciona que el atributo
<html lang="...">coincida con el idioma de la página - Verifica que las etiquetas
<link rel="alternate" hreflang="...">estén presentes - Revisa que las metaetiquetas estén en el idioma correcto
- Inspecciona que el atributo
Validación automatizada:
# Verifica el mapa del sitio
curl https://tu-sitio.com/sitemap.xml | grep hreflang
# Valida hreflang (usa herramienta en línea)
# Google Search Console > Internacionalización > hreflang
Lista de verificación SEO - Consulta reference/seo-checklist.md.
Si la validación falla:
- Revisa los mensajes de error cuidadosamente
- Verifica que los archivos de configuración no tengan errores tipográficos
- Confirma que los códigos de idioma sean correctos
- Vuelve al Paso 3 y corrige los problemas
Solo continúa cuando todas las validaciones pasen.
Notas Importantes
Estándares de Códigos de Idioma
Usa ISO 639-1 (códigos de dos letras) con variantes regionales opcionales:
en- Inglésja- Japonészh- Chino simplificadozh-hk- Chino tradicional (Hong Kong)pt- Portuguéspt-br- Portugués de Brasil
Consulta reference/locale-codes.md para la lista completa.
Implicaciones SEO
Una i18n correcta mejora el SEO al:
- Dirigirse a usuarios en su idioma nativo
- Evitar penalizaciones por contenido duplicado
- Ayudar a los motores de búsqueda a servir la versión de idioma correcta
Errores SEO comunes a evitar:
- ❌ Redirección automática basada en IP (impide que los motores de búsqueda rastreen todas las versiones)
- ❌ Etiquetas hreflang faltantes (causa problemas de contenido duplicado)
- ❌ Estructura de URL inconsistente entre idiomas
- ❌ Metaetiquetas sin traducir
Calidad de las Traducciones
Traducción con IA vs Traducción humana:
- ✅ IA: Rápida, rentable, buena para un borrador inicial
- ⚠️ IA: Puede perder matices culturales, necesita revisión
- ✅ Humana: Mejor calidad, adaptación cultural
- ⚠️ Humana: Más lenta, más costosa
Enfoque recomendado:
- Usa IA para generar traducciones iniciales
- Solicita a un hablante nativo que revise y refine
- Prueba con usuarios del mercado objetivo
- Itera basándote en los comentarios
Enrutamiento i18n en Next.js
El sistema usa next-intl para el enrutamiento:
- Detección automática de locale desde la URL
- Componente selector de idioma
- Navegación localizada
Configuración en i18n/locale.ts y i18n/request.ts.
Tareas Posteriores a la Internacionalización
Después de agregar idiomas:
- Envía el mapa del sitio actualizado a Google Search Console
- Crea propiedades separadas en Search Console para cada idioma/región
- Monitorea el tráfico orgánico internacional en Analytics
- Prueba A/B las traducciones si las tasas de conversión difieren por idioma
- Configura alertas para errores de rastreo internacional
Ubicación de los Scripts
Todos los scripts i18n están en el directorio scripts/:
i18n-add-languages.mjs- Agregar nuevos archivos de idiomai18n-add-schema.js- Agregar traducciones de datos estructurados
Materiales de Referencia
- WORKFLOW.md - Flujo de trabajo detallado paso a paso
- reference/hreflang-guide.md - Guía de implementación de hreflang
- reference/locale-codes.md - Referencia de códigos de idioma
- reference/seo-checklist.md - Lista de verificación SEO internacional
Para solucionar problemas, consulta la sección de resolución de problemas en WORKFLOW.md.