Internationalization
Configure locale routing, translation loading, and adding new languages in MuseMVP.
MuseMVP uses next-intl for full-site i18n across landing pages, app, docs, and blog. This guide covers the routing model, translation loading, and how to add a new locale.
Locale Routing Model
| Config | Description |
|---|---|
localePrefix | Default as-needed: default locale (en) has no URL prefix; others use prefix (e.g. /zh) |
| Default locale | config.i18n.defaultLocale, usually en |
| Locale cookie | NEXT_LOCALE for persisting user preference |
| Locale source | config.i18n.locales in src/config/index.ts |
as-needed Mode
With as-needed, / equals /en, and /zh is Chinese. Keeps default locale URLs clean and SEO-friendly.
Translation Loading
- Loader:
src/i18n/lib/messages.ts - Modular translations:
src/i18n/translations/{en,zh}/*.json(e.g.mvp.json,app.json)
Non-default locales are merged with the default locale; missing keys fall back to the default to avoid blank content.
Adding a New Locale
Add locale metadata in config.i18n.locales (label, appName, summary, headerMenuMap, footerConfig, etc.).
Create src/i18n/translations/{locale}/ and module JSON files.
Fill in navigation, footer, docs alias, etc., matching the structure of existing locales.
Verify routing, metadata output, and sitemap inclusion for the new locale.
// src/config/index.ts example
i18n: {
locales: {
en: { label: "English", ... },
zh: { label: "简体中文", ... },
ja: { label: "日本語", appName: "MuseMVP", ... }, // new
},
defaultLocale: "en",
}Common Pitfalls
Troubleshooting
First verify env vars, callback URLs, and keys; then debug business logic.
| Symptom | Possible cause |
|---|---|
| Runtime fallback warnings from missing translation modules | Check src/i18n/translations/{locale}/*.json exists and structure is correct |
| Menu labels updated but copy not synced | Ensure headerMenuMap, footerConfig match translation files |
| New locale routes work but docs/blog lack content | Content Collections and docsSource must support the locale; check meta.{locale}.json and MDX locale suffix |
Related Docs
- SEO — Sitemap and multi-locale URLs
- Basic Configuration — Brand and menu config