WXT i18n: @wxt-dev/i18n and messages.json

What @wxt-dev/i18n actually is

It is a build-time layer, not a runtime i18n engine. You author messages in a format that is pleasant to edit; the module compiles them into the flat Chrome catalogue format at build time. Nothing about the extension’s loading behaviour changes — the browser reads the same messages.json files it has read since Manifest V2.

Authoring                 Build step                 Shipped output
─────────────────────     ──────────────────────     ──────────────────────────
locales/en.yml        →   @wxt-dev/i18n module   →   _locales/en/messages.json
locales/de.yml        →   (WXT build)            →   _locales/de/messages.json
locales/fr.yml        →                          →   _locales/fr/messages.json

The right-hand column is the plain Chrome format.

If you have not met the target format yet, read the messages.json format explained first — everything WXT emits obeys those rules.

Setup

Two things are needed: register the module in wxt.config.ts and declare default_locale in the manifest block.

// wxt.config.ts
export default defineConfig({
  modules: ['@wxt-dev/i18n/module'],
  manifest: {
    default_locale: 'en',
  },
});

default_locale is not a WXT invention — it is the standard manifest field, and the standard rules apply to it. WXT writes it straight into the generated manifest. If you get it wrong, you get the ordinary Chrome load errors, which are catalogued in default_locale: rules and common errors.

Authoring formats: YAML, JSON, JSONC, JSON5, TOML

Message files can be written in any of five formats. All five compile to the same output, so the choice is purely about authoring ergonomics.

Most teams land on YAML for the same two reasons they land on it for Vue I18n locale files: comments survive code review, and indentation reads better than nested braces when a catalogue grows past a hundred keys.

i18n.t() vs browser.i18n.getMessage()

Both work, in the same project, at the same time. The module’s i18n.t() reads from the very same compiled catalogue that browser.i18n.getMessage() reads.

// The WXT helper — imported from the #i18n virtual module
import { i18n } from '#i18n';

i18n.t('helloWorld');

// The plain WebExtension API — works too
browser.i18n.getMessage('helloWorld');

Prefer i18n.t() in new code — it is what gives you typed keys and the plural API below. Keep browser.i18n.getMessage() in mind when you are porting an existing extension to WXT: your old call sites do not have to be rewritten in one pass.

Nested keys and how they flatten

The Chrome format has one flat namespace: every key in messages.json is a top-level property. WXT lets you nest at authoring time and reach the values with dot notation.

# locales/en.yml
welcome:
  title: Welcome to the extension
  subtitle: Let us get you set up

dialogs:
  confirmation:
    title: Are you sure?

Call sites:

i18n.t('welcome.title');
i18n.t('dialogs.confirmation.title');

The nesting is an authoring convenience only. After the build step the catalogue is flat, exactly as the format requires — the dotted path becomes the key. This is worth internalising before you hand files to a translation tool: the tool sees flat keys, not your YAML tree.

Plurals

Plurals are addressed by passing the count as the second argument to i18n.t().

i18n.t('items', 0);   // zero form
i18n.t('items', 1);   // singular form
i18n.t('items', 2);   // plural form

Custom substitutions are supplied as an array in the third argument, so count selection and substitution are independent:

i18n.t('items', 2, ['Multiple']);

Substitutions and the $$ escape

Substitutions use the standard positional tokens $1 through $9 — the same tokens the Chrome format uses, because that is what the compiled file contains.

To print a literal dollar sign, double it:

Type safety

WXT generates a wxt-i18n-structure.d.ts describing your catalogue, and you instantiate the helper against it:

createI18n<WxtI18nStructure>();

With that in place, a typo in a key is a compile error rather than an empty string in the UI — which is the more useful half of what the module buys you, given that the runtime API returns "" for a missing message and never throws.

Using the compiler outside WXT

The build API is published separately at @wxt-dev/i18n/build, so you can get the YAML-to-messages.json compilation in a project that does not use WXT at all. It exports parseMessagesFile, generateChromeMessagesFile and generateTypeFile.

import {
  parseMessagesFile,
  generateChromeMessagesFile,
  generateTypeFile,
} from '@wxt-dev/i18n/build';

const messages = await parseMessagesFile('path/locales/en.yml');

await generateChromeMessagesFile('dist/_locales/en/messages.json', messages);
await generateTypeFile('path/i18n-structure.d.ts', messages);

Note the output path: dist/_locales/en/messages.json. That is the real deliverable — a normal Chrome catalogue at a normal Chrome path. If you are on a different framework, this is the escape hatch that lets you keep YAML authoring without adopting WXT wholesale.

Translating a WXT project

There are exactly two places you can hand off for translation, and the right choice depends on whether you value structure or simplicity.

A pragmatic middle path most teams end up with: keep locales/en.yml as the hand-edited source of truth, build once to produce _locales/en/messages.json, translate that file, and commit the resulting non-English catalogues as build inputs. English stays pleasant to edit; the translated locales stay in the format every tool already understands.

Quick reference

Frequently asked questions

Related guides

• •The messages.json format explained — the format WXT compiles down to.
• •Chrome extension _locales structure — folder names, lookup order and fallbacks.
• •default_locale: rules and common errors — the manifest field WXT writes for you.
• •Plasmo i18n: the locales/ folder gotcha — the same problem in the other popular extension framework.