i18n y Localización
Mejores prácticas de Internacionalización (i18n) y Localización (L10n).
1. Conceptos Fundamentales
| Término | Significado |
|---|
| i18n | Internacionalización - hacer la aplicación traducible |
| L10n | Localización - traducciones reales |
| Locale | Idioma + Región (en-US, tr-TR) |
| RTL | Idiomas de derecha a izquierda (árabe, hebreo) |
2. Cuándo Usar i18n
| Tipo de Proyecto | ¿Necesita i18n? |
|---|
| Aplicación web pública | ✅ Sí |
| Producto SaaS | ✅ Sí |
| Herramienta interna | ⚠️ Quizás |
| Aplicación de una sola región | ⚠️ Considerar futuro |
| Proyecto personal | ❌ Opcional |
3. Patrones de Implementación
React (react-i18next)
import { useTranslation } from 'react-i18next';
function Bienvenida() {
const { t } = useTranslation();
return <h1>{t('bienvenida.titulo')}</h1>;
}
Next.js (next-intl)
import { useTranslations } from 'next-intl';
export default function Pagina() {
const t = useTranslations('Inicio');
return <h1>{t('titulo')}</h1>;
}
Python (gettext)
from gettext import gettext as _
print(_("Bienvenido a nuestra aplicación"))
4. Estructura de Archivos
locales/
├── es/
│ ├── common.json
│ ├── auth.json
│ └── errors.json
├── en/
│ ├── common.json
│ ├── auth.json
│ └── errors.json
└── ar/ # RTL
└── ...
5. Buenas Prácticas
HACER ✅
- Usar claves de traducción, no texto plano
- Agrupar traducciones por funcionalidad
- Soportar pluralización
- Manejar formatos de fecha/número según la configuración regional
- Planificar RTL desde el inicio
- Usar formato de mensaje ICU para cadenas complejas
NO HACER ❌
- Hardcodear cadenas en componentes
- Concatenar cadenas traducidas
- Asumir longitud del texto (el alemán es un 30% más largo)
- Olvidar el diseño RTL
- Mezclar idiomas en el mismo archivo
6. Problemas Comunes
| Problema | Solución |
|---|
| Traducción faltante | Recurrir al idioma predeterminado |
| Cadenas hardcodeadas | Usar un script linter/verificador |
| Formato de fecha | Usar Intl.DateTimeFormat |
| Formato de número | Usar Intl.NumberFormat |
| Pluralización | Usar formato de mensaje ICU |
7. Soporte RTL
.contenedor {
margin-inline-start: 1rem;
padding-inline-end: 1rem;
}
[dir="rtl"] .icono {
transform: scaleX(-1);
}
8. Lista de Verificación
Antes de publicar:
Script
| Script | Propósito | Comando |
|---|
scripts/i18n_checker.py | Detectar cadenas hardcodeadas y traducciones faltantes | python scripts/i18n_checker.py <ruta_del_proyecto> |
Cuándo Usar
Este skill es aplicable para ejecutar el flujo de trabajo o las acciones descritas en la visión general.
Limitaciones
- Use este skill solo cuando la tarea coincida claramente con el alcance descrito anteriormente.
- No trate el resultado como un sustituto de la validación, prueba o revisión experta específica del entorno.
- Deténgase y solicite aclaraciones si faltan entradas requeridas, permisos, límites de seguridad o criterios de éxito.