ESLint x OXLint Plugin

eslint-plugin-intlayer catches the kinds of i18n mistake TypeScript cannot:

1. Hardcoded text that never made it into a dictionary.
2. Dynamic calls that type-check and run, but that the Intlayer compiler cannot optimize.
3. Dead content — dictionaries and fields nothing in the project reads (opt-in).

Unknown dictionary keys, unknown field paths and missing locales are already compile errors, so the plugin does not repeat them.

Installation

npm install --save-dev eslint-plugin-intlayer

Requires ESLint 9 or later (flat config). ESLint 10 is supported.

Usage

The plugin runs in both ESLint and oxlint — the same rules, the same options.

{"jsPlugins": ["eslint-plugin-intlayer"],"rules": {  "intlayer/no-raw-text": "warn",  "intlayer/static-dictionary-key": "error",  "intlayer/no-dynamic-field-access": "error",  "intlayer/enforce-adapter-import": "warn"}}

Configs

recommended keeps no-raw-text at warn on purpose: pointing it at an existing codebase surfaces every untranslated string at once, which should not break your build on day one.

enforce-adapter-import is off by default — enable it explicitly if you want it.

no-unused-content is off in every config, strict included. It is the one rule that reads your Intlayer configuration and walks your source files from disk, so turning it on should be a deliberate choice rather than something a preset does for you.

Rules

no-raw-text

Reports user-facing text that is not declared in a dictionary. It uses the same detection as intlayer extract, so brand names, CSS classes and technical identifiers are ignored.

// ✗ Reported<h1>Welcome to our documentation</h1><input placeholder="Enter your email address" />// ✓ Fineconst { title } = useIntlayer("home");<h1>{title}</h1>

Content declaration files (*.content.ts, …) are skipped.

To fix a whole file at once, run npx intlayer extract and let the compiler move the strings into a dictionary for you.

Options

static-dictionary-key

Requires the dictionary key to be a string literal.

The compiler can only pre-load a dictionary when it can read the key directly at the call site. With a computed key it silently skips the optimization and bundles every dictionary instead.

// ✗ ReporteduseIntlayer(dictionaryKey);useIntlayer(`home-${suffix}`);getTranslations({ namespace: page });// ✗ A variable is still not a literalconst key = "home";useIntlayer(key);// ✓ FineuseIntlayer("home");getTranslations({ namespace: "home" });

This applies to useIntlayer, getIntlayer and every compat adapter (useTranslation, useTranslations, formatMessage, <FormattedMessage id>, <Trans i18nKey>, …).

no-dynamic-field-access

Requires the field you read from a dictionary to be statically known.

The compiler removes fields it does not see used. A computed access is invisible to it, so the read can return undefined at runtime.

// ✗ Reportedconst content = useIntlayer("home");content[fieldName];const t = useTranslations("home");t(messageKey);// ✓ Finecontent.title;content["title"];content.items[0];t("hero.title");

enforce-adapter-import

Prefers the @intlayer/* compat adapter over the original package. The original only resolves to Intlayer when the bundler alias is configured; the adapter always does. Autofixable with --fix.

// ✗ Reportedimport { useTranslation } from "react-i18next";import { getTranslations } from "next-intl/server";// ✓ Fineimport { useTranslation } from "@intlayer/react-i18next";import { getTranslations } from "@intlayer/next-intl/server";

no-unused-content

Off by default. Reports content nothing in your project reads, plus dictionary keys declared in more than one place.

export default {  key: "home", // ✗ Reported when no caller anywhere asks for "home"  content: {    title: t({ "en-GB": "Title", en: "Title" }),    // ✗ Reported when nothing reads `hero`    hero: {      subtitle: t({ "en-GB": "Subtitle", en: "Subtitle" }),    },  },};

Unlike the other rules, this one cannot answer from the file in front of it — a field is unused only relative to the whole project. On the first content declaration of a lint run it loads your Intlayer configuration, globs the source files that configuration declares (build.traversePattern, compiler.transformPattern) and runs the same usage analyser that powers @intlayer/lsp and the "unused" strikethrough in the VS Code extension. The result is cached for cacheTtl milliseconds, so the scan happens once per run rather than once per file.

Options

Lower cacheTtl when you lint from a long-lived editor server and want your edits reflected sooner; set baseDir when a single lint run spans several Intlayer projects in a monorepo.

It errs towards silence. A false positive here deletes a translation, so nothing is reported when the dictionary is consumed in a way the analysis cannot follow: the content object passed on as a whole, a translator function bound from it (const t = useTranslations("home")), a declaration reached through a direct import (useDictionary(myDictionary)), a nest() from another dictionary, or a field list made non-exhaustive by a spread. Single-file components (.vue, .svelte, .astro) count as using every field of the dictionaries they mention, because their script blocks are not parsed here.

reportDuplicateKeys reads the unmerged dictionaries the build writes under .intlayer/, so it stays quiet until the project has been built at least once. Two declarations sharing a key are merged, which is a legitimate pattern — the report exists because a field defined on both sides silently keeps only one of the two values.

The analyser is loaded from @intlayer/lsp, which ships as ESM. The rule therefore needs a Node version that can require() an ES module — Node 20.19+ or 22.12+. On anything older it reports nothing rather than failing the lint run.

Frameworks

Every rule works across all Intlayer integrations, including inside Vue, Svelte and Angular templates. You only need to tell ESLint which parser reads each file type.

Install only the parsers your project needs.

Known limitation. In Vue and Angular templates, an expression such as {{ content[key] }} is not checked by no-dynamic-field-access. Dynamic reads written in the script block are caught normally.