Mis traducciones no aparecen — ¿qué debo comprobar?
Si tu aplicación muestra claves en bruto o faltan traducciones para algunos idiomas, sigue esta lista de comprobación para diagnosticar el problema.
Si tu aplicación muestra claves en bruto (como common.welcome_title) en lugar de texto traducido, o faltan traducciones para algunos idiomas, sigue esta lista de comprobación.
Paso 1: ¿Están publicadas las traducciones?
La causa más común son traducciones no publicadas. Revisa tu panel de control:
- Ve a tu proyecto
- Busca el indicador "Cambios en borrador"
- Si hay cambios sin publicar, haz clic en "Publicar"
Solo las traducciones publicadas están disponibles en el CDN. Las traducciones en borrador solo son visibles en el panel de control.
Paso 2: Comprobar el CDN directamente
Verifica que las traducciones estén en el CDN obteniéndolas directamente:
# Comprobar el manifest (lista de locales disponibles)
curl https://cdn.better-i18n.com/your-org/your-project/manifest.json
# Comprobar traducciones para un locale específico
curl https://cdn.better-i18n.com/your-org/your-project/en/translations.json
Si el manifest devuelve un objeto vacío o { "fallback": true }, las traducciones aún no se han publicado.
Paso 3: Verificar la configuración del proyecto
Asegúrate de que la configuración de tu SDK coincide con tu proyecto:
// Comprueba el identificador del proyecto
const i18n = createI18n({
project: 'acme/dashboard', // Debe coincidir exactamente: org/project
defaultLocale: 'en', // Debe coincidir con tu locale fuente
});
Errores comunes:
- Formato
org/projectincorrecto (distingue mayúsculas y minúsculas) defaultLocaleno coincide con el idioma fuente en el panel de control- Usar una clave secreta donde se necesita una clave pública (o viceversa)
Paso 4: Comprobar la normalización de locales
El CDN usa códigos de locale BCP 47 en minúsculas. Si tu aplicación usa pt-BR pero el CDN espera pt-br, las traducciones no coincidirán.
El SDK maneja esto automáticamente mediante normalizeLocale(), pero si construyes URLs manualmente, asegúrate de ponerlas en minúsculas.
Paso 5: Comprobar la consola del navegador
Abre DevTools y busca:
- Pestaña Network — ¿hay alguna solicitud a
cdn.better-i18n.com? ¿Cuál es la respuesta? - Errores de consola — ¿errores como
BETTER_I18N_PROJECT is not configured? - Cuerpo de la respuesta — ¿el JSON de traducciones contiene tus claves?
Paso 6: Tiempo de caché
Después de publicar, hay un breve período en el que los cachés pueden servir datos obsoletos:
| Capa de caché | Tiempo máximo obsoleto |
|---|---|
| CDN edge | Purgado inmediatamente al publicar |
SDK en memoria (TtlCache) |
Hasta 60 segundos |
| Next.js ISR | Hasta 30 segundos (por defecto) |
| Caché HTTP del navegador | Hasta 60 segundos |
Espera 60 segundos después de publicar y fuerza la recarga del navegador (Cmd+Shift+R).
Paso 7: Comprobar la coincidencia de namespaces
Si usas namespaces, asegúrate de que coinciden entre tu código y el panel de control:
// El código usa el namespace 'common'
const t = useTranslations('common');
// El panel de control debe tener claves bajo el namespace 'common'
// common.welcome_title → "¡Bienvenido!"
Si tus claves están en el namespace predeterminado pero tu código solicita uno específico (o viceversa), las traducciones no se resolverán.
¿Sigues atascado?
Ejecuta el comando doctor del CLI:
better-i18n doctor
Esto comprueba la configuración, autenticación, conectividad API y problemas comunes de configuración.
Próximos pasos
¿Te resultó útil este artículo?