---
url: https://s00d.github.io/nuxt-i18n-micro/guide/runtime-overrides.md
description: Per-environment locale defaults at runtime.
---

# Runtime i18n Overrides

Use this guide when you need one build artifact to run with different locale defaults per environment (for example: different tenant instances).

## What can be overridden at runtime

The module supports safe runtime overrides for:

* `defaultLocale`
* `fallbackLocale`
* `disabledLocales`

These overrides are applied on top of the build-time config from `.nuxt/i18n.strategy.mjs` and `.nuxt/i18n.config.mjs`.

## What cannot be overridden at runtime

`strategy` (`no_prefix`, `prefix`, `prefix_except_default`, `prefix_and_default`) is a build-time concern because it affects generated route behavior.

If you pass a runtime strategy override, it is ignored and a warning is emitted.

## RuntimeConfig-based overrides

Provide runtime values under `runtimeConfig.public.i18nRuntime`:

```ts
export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      i18nRuntime: {
        defaultLocale: 'de',
        fallbackLocale: 'en',
        disabledLocales: ['fr'],
      },
    },
  },
})
```

## Environment variable overrides

You can also configure overrides via environment variables:

* `NUXT_I18N_DEFAULT_LOCALE`
* `NUXT_I18N_FALLBACK_LOCALE`
* `NUXT_I18N_DISABLED_LOCALES` (comma-separated, e.g. `fr,it`)

Fallback aliases are also supported:

* `NUXT_PUBLIC_I18N_RUNTIME_DEFAULT_LOCALE`
* `NUXT_PUBLIC_I18N_RUNTIME_FALLBACK_LOCALE`
* `NUXT_PUBLIC_I18N_RUNTIME_DISABLED_LOCALES`

## Validation rules

At runtime, the module validates overrides to avoid broken state:

* You cannot disable all locales.
* `defaultLocale` must point to an enabled locale.
* `fallbackLocale` must exist in declared locales.

If an override is invalid, the module keeps a safe value and logs a warning.

## Notes for multi-instance deployments

This runtime feature is designed for per-instance locale activation and defaults without rebuilding.

If instances require different URL strategies (`no_prefix` vs `prefix`), use separate builds for each strategy.

## Disabled locales and static payloads

`runtimeConfig.public.i18nRuntime.disabledLocales` updates routing, switcher, and the Nitro payload **handler** — but Nitro serves files under `public/` **before** that handler.

If `translationPayloads.publicAssets` (or Node SSR’s forced public copy) already wrote `/_locales/{page}/{locale}/data.json`, a runtime disable cannot hide that file. Prefer `locale.disabled: true` at build so premerge does not emit that locale’s static payloads.