@astroscope/eslint-plugin-i18n 0.1.0

package/README.md

@@ -0,0 +1,162 @@
+# @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
+
+```bash
+npm install -D @astroscope/eslint-plugin-i18n
+```
+
+## Setup
+
+```js
+// 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.
+
+```ts
+// 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.
+
+```ts
+// 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.
+
+```ts
+// 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.
+
+```ts
+// 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.
+
+```ts
+// 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.
+
+```astro
+<!-- 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.).
+
+```tsx
+// warns
+<div>Hello World</div>
+<button>Submit</button>
+
+// no warning
+<div className="container" />
+<div>{t('greeting', 'Hello World')}</div>
+```
+
+#### Options
+
+```js
+'@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:
+
+```js
+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

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+import { ESLint, Linter } from 'eslint';
+
+declare const DEFAULT_IGNORE_ATTRIBUTES: string[];
+
+declare const plugin: ESLint.Plugin & {
+    configs: Record<string, Linter.Config>;
+};
+
+export { DEFAULT_IGNORE_ATTRIBUTES, plugin as default };

package/dist/index.js

@@ -0,0 +1,350 @@
+// src/index.ts
+import { readFileSync } from "fs";
+import { dirname, resolve } from "path";
+import { fileURLToPath } from "url";
+
+// src/rules/no-module-level-t.ts
+var noModuleLevelT = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "forbid `t()` calls at module level (outside functions)"
+    },
+    messages: {
+      moduleLevelT: "`t()` must not be called at module level. It requires request context (server) or hydrated translations (client). Move it inside a function or component."
+    },
+    schema: []
+  },
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (node.callee.type !== "Identifier" || node.callee.name !== "t") return;
+        let scope = context.sourceCode.getScope(node);
+        while (scope) {
+          if (scope.type === "function") return;
+          scope = scope.upper;
+        }
+        context.report({ node, messageId: "moduleLevelT" });
+      }
+    };
+  }
+};
+
+// src/rules/no-raw-strings-in-jsx.ts
+var DEFAULT_IGNORE_PATTERNS = [
+  /^\s*$/,
+  // whitespace only
+  /^\s*[{}]\s*/,
+  // just braces
+  /^[0-9.]+$/,
+  // numbers
+  /^\s*\|\s*$/,
+  // pipe separators
+  /^\s*[•·–—]\s*$/
+  // bullets / dashes
+];
+var DEFAULT_IGNORE_ATTRIBUTES = [
+  "className",
+  "class",
+  "id",
+  "key",
+  "href",
+  "src",
+  "type",
+  "name",
+  "value",
+  "role",
+  "htmlFor",
+  "target",
+  "rel",
+  "method",
+  "action",
+  "data-testid",
+  "data-cy",
+  "slot"
+];
+var noRawStringsInJsx = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "warn when raw strings appear in JSX that may need translation"
+    },
+    messages: {
+      rawString: 'Raw string "{{ text }}" in JSX. Consider using `t()` for user-facing text.'
+    },
+    schema: [
+      {
+        type: "object",
+        properties: {
+          ignorePatterns: {
+            type: "array",
+            items: { type: "string" }
+          },
+          ignoreAttributes: {
+            type: "array",
+            items: { type: "string" }
+          }
+        },
+        additionalProperties: false
+      }
+    ]
+  },
+  create(context) {
+    const options = context.options[0] ?? {};
+    const userPatterns = (options.ignorePatterns ?? []).map((p) => new RegExp(p));
+    const allPatterns = [...DEFAULT_IGNORE_PATTERNS, ...userPatterns];
+    const ignoreAttributes = /* @__PURE__ */ new Set([...DEFAULT_IGNORE_ATTRIBUTES, ...options.ignoreAttributes ?? []]);
+    function shouldIgnore(text) {
+      return allPatterns.some((p) => p.test(text));
+    }
+    function isInsideIgnoredAttribute(node) {
+      const parent = node.parent;
+      if (parent?.type === "JSXAttribute") {
+        const attrName = parent.name?.type === "JSXIdentifier" ? parent.name.name : parent.name?.type === "JSXNamespacedName" ? `${parent.name.namespace.name}:${parent.name.name.name}` : null;
+        if (attrName && ignoreAttributes.has(attrName)) return true;
+      }
+      if (parent?.type === "JSXExpressionContainer" && parent.parent?.type === "JSXAttribute") {
+        const attrName = parent.parent.name?.type === "JSXIdentifier" ? parent.parent.name.name : null;
+        if (attrName && ignoreAttributes.has(attrName)) return true;
+      }
+      return false;
+    }
+    return {
+      JSXText(node) {
+        const text = node.value;
+        if (shouldIgnore(text)) return;
+        const trimmed = text.trim();
+        if (!trimmed) return;
+        context.report({
+          node,
+          messageId: "rawString",
+          data: { text: trimmed.length > 40 ? `${trimmed.slice(0, 40)}...` : trimmed }
+        });
+      },
+      // string literals used as JSX attribute values: <div title="Hello" />
+      JSXAttribute(node) {
+        if (!node.value) return;
+        if (node.value.type !== "Literal" || typeof node.value.value !== "string") return;
+        const text = node.value.value;
+        if (shouldIgnore(text)) return;
+        if (isInsideIgnoredAttribute(node)) return;
+        const attrName = node.name?.type === "JSXIdentifier" ? node.name.name : node.name?.type === "JSXNamespacedName" ? `${node.name.namespace.name}:${node.name.name.name}` : null;
+        if (attrName && ignoreAttributes.has(attrName)) return;
+        context.report({
+          node: node.value,
+          messageId: "rawString",
+          data: { text: text.length > 40 ? `${text.slice(0, 40)}...` : text }
+        });
+      }
+    };
+  }
+};
+
+// src/rules/no-t-reassign.ts
+var noTReassign = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "forbid aliasing or reassigning the `t` function"
+    },
+    messages: {
+      noAlias: "Do not alias `t` to another name. The build-time extractor only recognizes `t()` calls.",
+      noReassign: "Do not reassign `t`. The build-time extractor only recognizes the original `t()` import."
+    },
+    schema: []
+  },
+  create(context) {
+    let tImported = false;
+    return {
+      ImportDeclaration(node) {
+        for (const specifier of node.specifiers) {
+          if (specifier.type !== "ImportSpecifier") continue;
+          if (specifier.imported.type !== "Identifier") continue;
+          if (specifier.imported.name !== "t") continue;
+          tImported = true;
+          if (specifier.local.name !== "t") {
+            context.report({ node: specifier, messageId: "noAlias" });
+          }
+        }
+      },
+      // const translate = t
+      VariableDeclarator(node) {
+        if (!tImported) return;
+        if (node.init?.type !== "Identifier" || node.init.name !== "t") return;
+        context.report({ node, messageId: "noReassign" });
+      },
+      // translate = t
+      AssignmentExpression(node) {
+        if (!tImported) return;
+        if (node.right.type !== "Identifier" || node.right.name !== "t") return;
+        context.report({ node, messageId: "noReassign" });
+      }
+    };
+  }
+};
+
+// src/rules/prefer-x-directives.ts
+var DIRECTIVE_MAP = {
+  load: "load-x",
+  visible: "visible-x",
+  idle: "idle-x",
+  media: "media-x",
+  only: "only-x"
+};
+var preferXDirectives = {
+  meta: {
+    type: "suggestion",
+    fixable: "code",
+    docs: {
+      description: "prefer `client:*-x` directives over `client:*` for i18n-aware hydration"
+    },
+    messages: {
+      preferX: "Use `client:{{ replacement }}` instead of `client:{{ original }}`. The -x variant preloads translations before hydration."
+    },
+    schema: []
+  },
+  create(context) {
+    return {
+      JSXAttribute(node) {
+        const name = node.name;
+        if (!name || name.type !== "JSXNamespacedName") return;
+        if (name.namespace?.name !== "client") return;
+        const directiveName = name.name?.name;
+        const replacement = DIRECTIVE_MAP[directiveName];
+        if (!replacement) return;
+        context.report({
+          node,
+          messageId: "preferX",
+          data: { original: directiveName, replacement },
+          fix(fixer) {
+            return fixer.replaceText(name.name, replacement);
+          }
+        });
+      }
+    };
+  }
+};
+
+// src/rules/t-import-source.ts
+var ALLOWED_SOURCES = ["@astroscope/i18n/translate"];
+var tImportSource = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "enforce that `t` is imported from @astroscope/i18n"
+    },
+    messages: {
+      wrongSource: '`t` must be imported from {{ allowed }}, got "{{ source }}".'
+    },
+    schema: []
+  },
+  create(context) {
+    return {
+      ImportDeclaration(node) {
+        const source = node.source.value;
+        if (typeof source !== "string") return;
+        for (const specifier of node.specifiers) {
+          if (specifier.type === "ImportSpecifier" && specifier.imported.type === "Identifier" && specifier.imported.name === "t" && !ALLOWED_SOURCES.includes(source)) {
+            context.report({
+              node: specifier,
+              messageId: "wrongSource",
+              data: {
+                source,
+                allowed: ALLOWED_SOURCES.join(" or ")
+              }
+            });
+          }
+        }
+      }
+    };
+  }
+};
+
+// src/rules/t-requires-meta.ts
+var tRequiresMeta = {
+  meta: {
+    type: "suggestion",
+    docs: {
+      description: "require the second argument (fallback/meta) in `t()` calls"
+    },
+    messages: {
+      missingMeta: '`t()` should include a fallback as the second argument for development DX. Use `t(key, "fallback")` or `t(key, { fallback: "..." })`.'
+    },
+    schema: []
+  },
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (node.callee.type !== "Identifier" || node.callee.name !== "t") return;
+        if (node.arguments.length < 1) return;
+        if (node.arguments.length < 2) {
+          context.report({ node, messageId: "missingMeta" });
+        }
+      }
+    };
+  }
+};
+
+// src/rules/t-static-key.ts
+var tStaticKey = {
+  meta: {
+    type: "problem",
+    docs: {
+      description: "require the first argument of `t()` to be a static string literal"
+    },
+    messages: {
+      dynamicKey: "`t()` key must be a static string literal. Dynamic keys cannot be extracted at build time."
+    },
+    schema: []
+  },
+  create(context) {
+    return {
+      CallExpression(node) {
+        if (node.callee.type !== "Identifier" || node.callee.name !== "t") return;
+        const firstArg = node.arguments[0];
+        if (!firstArg) return;
+        if (firstArg.type === "Literal" && typeof firstArg.value === "string") return;
+        if (firstArg.type === "TemplateLiteral" && firstArg.expressions.length === 0) return;
+        context.report({ node: firstArg, messageId: "dynamicKey" });
+      }
+    };
+  }
+};
+
+// src/index.ts
+var pkg = JSON.parse(readFileSync(resolve(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf-8"));
+var plugin = {
+  meta: {
+    name: "@astroscope/eslint-plugin-i18n",
+    version: pkg.version
+  },
+  rules: {
+    "t-import-source": tImportSource,
+    "no-module-level-t": noModuleLevelT,
+    "t-static-key": tStaticKey,
+    "t-requires-meta": tRequiresMeta,
+    "prefer-x-directives": preferXDirectives,
+    "no-raw-strings-in-jsx": noRawStringsInJsx,
+    "no-t-reassign": noTReassign
+  },
+  configs: {}
+};
+plugin.configs.recommended = {
+  plugins: {
+    "@astroscope/i18n": plugin
+  },
+  rules: {
+    "@astroscope/i18n/t-import-source": "error",
+    "@astroscope/i18n/no-module-level-t": "error",
+    "@astroscope/i18n/t-static-key": "error",
+    "@astroscope/i18n/t-requires-meta": "warn",
+    "@astroscope/i18n/no-t-reassign": "error",
+    "@astroscope/i18n/prefer-x-directives": "error",
+    "@astroscope/i18n/no-raw-strings-in-jsx": "warn"
+  }
+};
+var index_default = plugin;
+export {
+  DEFAULT_IGNORE_ATTRIBUTES,
+  index_default as default
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@astroscope/eslint-plugin-i18n",
+  "version": "0.1.0",
+  "description": "ESLint rules for @astroscope/i18n",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/smnbbrv/astroscope.git",
+    "directory": "packages/eslint-plugin-i18n"
+  },
+  "keywords": [
+    "eslint",
+    "eslintplugin",
+    "eslint-plugin",
+    "astroscope",
+    "i18n"
+  ],
+  "author": "smnbbrv",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/smnbbrv/astroscope/issues"
+  },
+  "homepage": "https://github.com/smnbbrv/astroscope/tree/main/packages/eslint-plugin-i18n#readme",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix"
+  },
+  "devDependencies": {
+    "eslint": "^9.39.3",
+    "tsup": "^8.5.1",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "eslint": "^9.0.0 || ^10.0.0"
+  }
+}