@astroscope/eslint-plugin-i18n

Note: This package is in active development. APIs may change between versions.

ESLint rules for projects using @astroscope/i18n. Enforces correct t() usage, catches build-time extraction issues, and promotes i18n best practices.

Installation

npm install -D @astroscope/eslint-plugin-i18n

Setup

// eslint.config.js
import i18n from '@astroscope/eslint-plugin-i18n';

export default [
  i18n.configs.recommended,
];

Rules

| Rule | Severity | Fixable | Description | |------|----------|---------|-------------| | @astroscope/i18n/t-import-source | error | | t must be imported from @astroscope/i18n/translate | | @astroscope/i18n/no-module-level-t | error | | t() must not be called at module level (needs request context on server, hydrated translations on client) | | @astroscope/i18n/t-static-key | error | | first argument must be a static string literal (dynamic keys break build-time extraction) | | @astroscope/i18n/t-requires-meta | warn | | second argument (fallback/meta) should be provided for development DX | | @astroscope/i18n/no-t-reassign | error | | forbids aliasing or reassigning t (the extractor only recognizes t() calls) | | @astroscope/i18n/prefer-x-directives | error | yes | prefer client:load-x over client:load (and visible, idle, media, only) for i18n-aware hydration | | @astroscope/i18n/no-raw-strings-in-jsx | warn | | warns when raw strings appear in JSX that may need translation |

Rule Details

t-import-source

Ensures t is only imported from the correct @astroscope/i18n entrypoints.

// good
import { t } from '@astroscope/i18n/translate';

// bad
import { t } from 'i18next';
import { t } from './my-translate';

no-module-level-t

Forbids calling t() at module scope. On the server, t() reads from AsyncLocalStorage (request context). On the client, it reads from window.__i18n__. Neither is available during module evaluation.

// good
function render() {
  return t('key', 'fallback');
}

// bad
const title = t('key', 'fallback');

t-static-key

The first argument must be a string literal. Dynamic keys cannot be extracted at build time by the Babel plugin.

// good
t('checkout.title', 'Checkout');

// bad
t(key, 'fallback');
t('prefix.' + suffix, 'fallback');
t(`prefix.${suffix}`, 'fallback');

t-requires-meta

The second argument (fallback string or meta object) provides the fallback text shown during development when translations are missing.

// good
t('key', 'Hello World');
t('key', { fallback: 'Hello World', description: 'Greeting' });

// bad (no fallback — shows raw key in dev)
t('key');

no-t-reassign

The build-time extractor only recognizes t() calls by name. Aliasing or reassigning breaks extraction.

// good
import { t } from '@astroscope/i18n/translate';

// bad
import { t as translate } from '@astroscope/i18n/translate';
const translate = t;

prefer-x-directives

The -x client directives preload translations before hydration. They are a strict superset of the standard directives — components without translations work identically.

<!-- good -->
<Cart client:load-x />
<Cart client:visible-x />

<!-- bad -->
<Cart client:load />
<Cart client:visible />

no-raw-strings-in-jsx

Warns when JSX contains raw string literals that may need translation. Ignores whitespace, numbers, and common non-translatable attributes (className, href, type, etc.).

// warns
<div>Hello World</div>
<button>Submit</button>

// no warning
<div className="container" />
<div>{t('greeting', 'Hello World')}</div>

Options

'@astroscope/i18n/no-raw-strings-in-jsx': ['warn', {
  // additional regex patterns to ignore (applied to text content)
  ignorePatterns: ['^TODO'],
  // additional attribute names to ignore
  ignoreAttributes: ['data-tooltip'],
}]

The default ignore list is exported as DEFAULT_IGNORE_ATTRIBUTES for consumers who want to extend it:

import i18n, { DEFAULT_IGNORE_ATTRIBUTES } from '@astroscope/eslint-plugin-i18n';

// ...
'@astroscope/i18n/no-raw-strings-in-jsx': ['warn', {
  ignoreAttributes: [...DEFAULT_IGNORE_ATTRIBUTES, 'alt', 'data-tooltip'],
}]

Compatibility

• ESLint 9 and 10
• Works with eslint-plugin-astro for .astro file support

License

MIT