withastro/astro · error · AstroError

i18nNotEnabled

i18nNotEnabled

Error message

The `astro:i18n` module cannot be used without enabling `i18n` in your Astro config.

What it means

The `astro:i18n` virtual module (getRelativeLocaleUrl, pathHasLocale, and friends) only exists when internationalization is configured. Its Vite plugin throws i18nNotEnabled at resolve time when an import of `astro:i18n` is resolved while `i18n` is undefined in the Astro config.

Solutions

1. Enable i18n in astro.config: `i18n: { defaultLocale: 'en', locales: ['en', 'es'] }`.
2. If you do not want i18n, remove the `astro:i18n` imports (search the repo for them).
3. If the import comes from a dependency, either enable i18n or drop/replace that dependency.

Example fix

// before - astro.config.mjs
export default defineConfig({ integrations: [react()] }); // component imports 'astro:i18n'

// after
export default defineConfig({
  i18n: { defaultLocale: 'en', locales: ['en', 'es'] },
  integrations: [react()],
});

// repo lint: flag astro:i18n imports when the config has no i18n block
import { readFileSync } from 'node:fs';
const config = readFileSync('astro.config.mjs', 'utf8');
const src = readFileSync('src/pages/index.astro', 'utf8');
if (src.includes("from 'astro:i18n'") && !/\bi18n\s*:/.test(config)) {
  console.error('enable i18n in astro.config before importing astro:i18n');
  process.exit(1);
}

When it happens

Trigger: Importing `astro:i18n` in any component, script, or module when astro.config has no `i18n` property; adding a dependency or copied-in component that uses astro:i18n to a project without i18n enabled; removing the i18n config while imports remain in the codebase.

Common situations: Copying an i18n-aware component from another project or a starter template; beginning an i18n migration by adding imports before touching the config; disabling i18n later and missing stray imports.

Related errors

• MissingIndexForInternationalizationError
• MissingLocaleError
• i18nNoLocaleFoundInPath
• IncorrectStrategyForI18n
• InvalidI18nMiddlewareConfiguration

AI-assisted analysis of withastro/astro@52e6c34790 (2026-08-18). Data as JSON: /api/errors/f31545f59850b2bf. Report an issue: GitHub.

Appendix: source

Thrown at packages/astro/src/i18n/vite-plugin-i18n.ts:24

const VIRTUAL_MODULE_ID = 'astro:i18n';

type AstroInternationalization = {
	settings: AstroSettings;
};

export default function astroInternationalization({
	settings,
}: AstroInternationalization): vite.Plugin {
	const { i18n } = settings.config;
	return {
		name: VIRTUAL_MODULE_ID,
		enforce: 'pre',
		resolveId: {
			filter: {
				id: new RegExp(`^${VIRTUAL_MODULE_ID}$`),
			},
			handler() {
				if (i18n === undefined) throw new AstroError(AstroErrorData.i18nNotEnabled);
				return this.resolve('astro/virtual-modules/i18n.js');
			},
		},
	};
}

View on GitHub (pinned to 52e6c34790)