My translations aren't showing — what do I check?

If your app shows raw keys (like common.welcome_title) instead of translated text, or translations are missing for some languages, work through this checklist.

Step 1: Are translations published?

The most common cause is unpublished translations. Check your dashboard:

1. Go to your project
2. Look for the "Draft changes" indicator
3. If there are unpublished changes, click "Publish"

Only published translations are available on the CDN. Draft translations are visible only in the dashboard.

Step 2: Check the CDN directly

Verify translations are on the CDN by fetching them directly:

# Check the manifest (list of available locales)
curl https://cdn.better-i18n.com/your-org/your-project/manifest.json

# Check translations for a specific locale
curl https://cdn.better-i18n.com/your-org/your-project/en/translations.json

If the manifest returns an empty object or { "fallback": true }, your translations haven't been published yet.

Step 3: Verify project configuration

Make sure your SDK configuration matches your project:

// Double-check the project identifier
const i18n = createI18n({
  project: 'acme/dashboard', // Must match exactly: org/project
  defaultLocale: 'en',       // Must match your source locale
});

Common mistakes:

• Wrong org/project format (case-sensitive)
• Mismatched defaultLocale vs. source language in dashboard
• Using a secret key where a public key is needed (or vice versa)

Step 4: Check locale normalization

The CDN uses lowercase BCP 47 locale codes. If your app uses pt-BR but the CDN expects pt-br, translations won't match.

The SDK handles this automatically via normalizeLocale(), but if you're constructing URLs manually, make sure to lowercase them.

Step 5: Check the browser console

Open DevTools and look for:

• Network tab — is there a request to cdn.better-i18n.com? What's the response?
• Console errors — any BETTER_I18N_PROJECT is not configured or similar errors?
• Response body — does the translations JSON contain your keys?

Step 6: Cache timing

After publishing, there's a brief window where caches may serve stale data:

Cache layer	Max stale time
CDN edge	Purged immediately on publish
SDK in-memory (TtlCache)	Up to 60 seconds
Next.js ISR	Up to 30 seconds (default)
Browser HTTP cache	Up to 60 seconds

Wait 60 seconds after publishing and hard-refresh your browser (Cmd+Shift+R).

Step 7: Check namespace matching

If you're using namespaces, make sure they match between your code and dashboard:

// Code uses 'common' namespace
const t = useTranslations('common');

// Dashboard must have keys under 'common' namespace
// common.welcome_title → "Welcome!"

If your keys are in the default namespace but your code requests a specific one (or vice versa), translations won't resolve.

Still stuck?

Run the CLI doctor command:

better-i18n doctor

This checks configuration, authentication, API connectivity, and common setup issues.

Next steps

• Published but app still shows old translations
• CLI doctor errors