¿Qué hace Experto en I18n?
Descripción general
Realiza una configuración completa de i18n junto con una auditoría: configura el framework de internacionalización, reemplaza las cadenas visibles para el usuario con claves, garantiza la paridad entre idiomas y valida la pluralización y el formato para en-US y zh-CN.
Capacidades principales
- Selección y configuración de librerías (React, Next.js, Vue).
- Arquitectura de claves y organización de archivos de localización.
- Generación de traducciones y estrategia de calidad (IA, profesional, manual).
- Enrutamiento y detección/cambio de idioma.
- Localización SEO y de metadatos (cuando sea aplicable).
- Soporte RTL (solo si los idiomas objetivo incluyen RTL).
Entradas de alcance (preguntar si no está claro)
- Framework y estilo de enrutamiento.
- Estado actual de i18n (ninguno, parcial, heredado).
- Idiomas objetivo (por defecto: en-US + zh-CN).
- Necesidades de calidad de traducción (IA vs profesional vs manual).
- Formatos de localización en uso (JSON, YAML, PO, XLIFF).
- Requisitos de formalidad cultural (si los hay).
Flujo de trabajo (Auditar -> Corregir -> Validar)
-
Confirmar el alcance y los idiomas objetivo
- Identificar el framework de i18n y las ubicaciones de los archivos de localización.
- Confirmar los idiomas; por defecto usar en-US + zh-CN cuando se especifique.
-
Configurar la base de i18n (si falta)
- Elegir una librería adecuada al framework (ej., React: react-i18next; Next.js: next-intl; Vue: vue-i18n).
- Instalar paquetes y crear el archivo de entrada/configuración de i18n.
- Conectar el proveedor en la raíz de la aplicación y cargar los recursos de localización.
- Agregar un conmutador de idioma y persistencia (ruta/parámetro/localStorage) según corresponda.
- Establecer la estructura de archivos de localización y los espacios de nombres de claves.
- Si el enrutamiento tiene en cuenta el idioma, definir la estrategia de segmento de idioma desde el principio (subruta, subdominio, parámetro de consulta).
- Si los metadatos son visibles para el usuario, incluir la traducción de títulos/descripciones.
-
Auditar el uso de claves y la paridad entre idiomas
- Ejecutar:
python scripts/i18n_audit.py --src <raíz-src> --locale <ruta/a/en-US.json> --locale <ruta/a/zh-CN.json> - Tratar las claves faltantes o las brechas de paridad como bloqueantes.
- Verificar manualmente las claves dinámicas (
t(var)).
- Ejecutar:
-
Encontrar cadenas sin procesar visibles para el usuario
- Buscar:
rg -n --glob '<src>/**/*.{ts,tsx,js,jsx}' "<[^>]+>[^<{]*[A-Za-z][^<{]*<" rg -n --glob '<src>/**/*.{ts,tsx,js,jsx}' "aria-label=\"[^\"]+\"|title=\"[^\"]+\"|placeholder=\"[^\"]+\"" - Localizar etiquetas de accesibilidad.
- Buscar:
-
Reemplazar cadenas con claves
- Usar
t('namespace.key')para texto de interfaz. - Para plurales usar
t('key', { count })+ claves_one/_other. - Usar formateadores Intl/de la aplicación para hora/fecha/número.
- Usar
-
Localizar el manejo de errores (crítico)
- Mapear códigos de error a claves localizadas; mostrar solo la interfaz localizada.
- Registrar solo los detalles del error sin procesar.
- Proporcionar una alternativa localizada para códigos desconocidos.
-
Actualizar archivos de localización
- Agregar claves faltantes en ambos idiomas.
- Mantener los marcadores de posición consistentes; evitar renombrar a menos que se solicite.
- Generar traducciones usando el método acordado; preservar marcadores de posición y reglas de plurales.
-
Validar
- Volver a ejecutar la auditoría hasta que no haya problemas de claves faltantes o de paridad.
- Validar JSON (ej.,
python -m json.tool <archivo>). - Actualizar las pruebas que verifican el texto visible.
Barreras de seguridad
- Nunca exponer
error.messagesin procesar en la interfaz de usuario; mostrar solo cadenas localizadas. - No agregar idiomas adicionales a menos que se solicite explícitamente.
- Preferir espacios de nombres estructurados (ej.,
errors.*,buttons.*,workspace.*). - Mantener las traducciones concisas y consistentes.
- Algunos términos técnicos/de marca deben permanecer sin traducir (ej., nombre del producto, API, MCP, Bash).
Entregables (salidas esperadas)
- Configuración de i18n / conexión del proveedor.
- Archivos de localización para cada idioma objetivo.
- Cadenas de interfaz reemplazadas con claves estables.
- Conmutador de idioma y persistencia (si corresponde).
- Pruebas actualizadas para verificar el texto visible.
Guía de arquitectura (mantener concisa)
- Estructura de claves: preferir espacios de nombres anidados por área (ej.,
common.buttons.save,pricing.tier.pro). - Organización de archivos: un archivo por idioma o espacios de nombres por idioma; mantener las claves sincronizadas entre idiomas.
- Marcadores de posición: preservar exactamente
{nombre}/{{nombre}}; validar plurales según las reglas del idioma. - Formateo: usar ayudantes Intl/de la aplicación para formateo de fecha, hora, número y listas.
- SEO/metadatos: localizar títulos y descripciones si la aplicación los expone.
- RTL: solo necesario para idiomas RTL; usar propiedades CSS lógicas y probar el diseño.
- Superficies no web (diálogos del proceso principal de Electron, indicaciones de CLI, menús nativos) también necesitan localización.
Notas de rendimiento (breve)
- Cargar perezosamente los paquetes de localización cuando la aplicación lo soporte.
- Dividir archivos de localización grandes por espacio de nombres.
Modos de fallo (lista de vigilancia)
- Traducciones faltantes: recurrir al idioma por defecto y registrar advertencias.
- Problemas de diseño RTL: verificar CSS lógico y probar páginas.
- SEO faltante: asegurar que los enlaces alternativos y metadatos estén localizados cuando sea aplicable.
Lista de verificación de validación (breve)
- Sin claves faltantes y sin cadenas sin procesar en la interfaz.
- El cambio de idioma funciona y persiste.
- Plurales y formato verificados en ambos idiomas.
- Idioma de respaldo configurado.
Recursos
scripts/
scripts/i18n_audit.py: Extrae el uso det('key')y lo compara con los archivos JSON de localización.
Desencadenantes de activación
Mapear códigos de error a mensajes localizados, y validar la paridad de claves, pluralización y formato.