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 is only synthesized by the i18n Vite plugin when `settings.config.i18n` is defined. In `resolveId`, if `i18n === undefined`, the plugin throws `i18nNotEnabled` rather than resolving the module, because there is no i18n configuration to generate it from.

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 d081033d5f)

Solutions

1. Add an `i18n` section to `astro.config.mjs` (at minimum `i18n: { defaultLocale, locales }`).
2. Remove the `astro:i18n` import if you do not need internationalization.
3. If shipping a reusable component, gate the import behind a check or document that i18n config is required.

Example fix

// before — astro.config.mjs has no i18n key, yet code imports the module
import * as i18n from 'astro:i18n'

// after — enable i18n in config
export default defineConfig({
  i18n: { defaultLocale: 'en', locales: ['en', 'es'] },
})

function assertI18nEnabled(config) {
  if (!config.i18n) {
    throw new Error('Enable i18n in astro.config before importing astro:i18n');
  }
}

function i18nIsEnabled(config) {
  return config.i18n !== undefined && Array.isArray(config.i18n.locales);
}

null

When it happens

Trigger: Importing `astro:i18n` in any module when `astro.config` has no `i18n` block (or it is undefined).

Common situations: Copying code from an i18n-enabled project into one without i18n configured; removing the `i18n` config but leaving imports in place; a third-party integration/component that unconditionally imports `astro:i18n`.

Related errors

• MissingMiddlewareForInternationalization
• ServerOnlyModule
• MissingIndexForInternationalizationError
• EnvPrefixConflictsWithSecret
• MissingLocaleError

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