i18n y Localización
Regla de Lectura Selectiva
Empieza por:
references/senior-master-standard.mdreferences/usage-routing.mdreferences/quality-checklist.md
Luego carga solo los documentos, scripts, activos o ejemplos heredados que coincidan con la tarea real del usuario.
Prácticas recomendadas de internacionalización (i18n) y localización (L10n).
1. Conceptos Clave
| Término | Significado |
|---|---|
| i18n | Internacionalización - hacer que la aplicación sea 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 | ¿i18n Necesario? |
|---|---|
| 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 Welcome() {
const { t } = useTranslation();
return <h1>{t('welcome.title')}</h1>;
}
Next.js (next-intl)
import { useTranslations } from 'next-intl';
export default function Page() {
const t = useTranslations('Home');
return <h1>{t('title')}</h1>;
}
Python (gettext)
from gettext import gettext as _
print(_("Welcome to our app"))
4. Estructura de Archivos
locales/
├── en/
│ ├── common.json
│ ├── auth.json
│ └── errors.json
├── tr/
│ ├── common.json
│ ├── auth.json
│ └── errors.json
└── ar/ # RTL
└── ...
5. Mejores Prácticas
HACER ✅
- Usar claves de traducción, no texto sin formato
- Organizar traducciones por funcionalidad
- Soportar pluralización
- Manejar formatos de fecha/número según configuración regional
- Planificar RTL desde el inicio
- Usar formato de mensaje ICU para cadenas complejas
NO HACER ❌
- Codificar 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 codificadas | Usar script de 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
/* Propiedades Lógicas CSS */
.container {
margin-inline-start: 1rem; /* No margin-left */
padding-inline-end: 1rem; /* No padding-right */
}
[dir="rtl"] .icon {
transform: scaleX(-1);
}
8. Lista de Verificación
Antes de publicar:
- Todas las cadenas visibles para el usuario usan claves de traducción
- Existen archivos de configuración regional para todos los idiomas soportados
- El formato de fecha/número usa la API Intl
- Diseño RTL probado (si aplica)
- Idioma de respaldo configurado
- No hay cadenas codificadas en los componentes
Script
| Script | Propósito | Comando |
|---|---|---|
scripts/i18n_checker.py | Detectar cadenas codificadas y traducciones faltantes | python scripts/i18n_checker.py <project_path> |