@liam-public/node-i18n-lint 0.1.0

package/README.md

@@ -0,0 +1,33 @@
+# @liam-public/node-i18n-lint
+
+Detects **hardcoded, untranslated strings** in JSX/TSX so you can wrap them in `t()`. Parses with
+the TypeScript compiler API (not regex) and flags three things:
+
+- **JSX text** — `<button>Add Source</button>`
+- **User-facing attributes** — `placeholder`, `title`, `alt`, `aria-label`, `label`, …
+- **Bare string literals in JSX** — `<span>{'No sources found.'}</span>`
+
+It ignores numbers, URLs, CSS selectors, whitespace, `t(...)` calls, and any line carrying an
+`i18n-ignore` comment.
+
+## CLI
+
+```bash
+# scan a directory (or files); exits non-zero if any are found (CI-friendly)
+npx i18n-lint src/
+
+# example output
+src/pages/sources/SourcesPage.tsx:42:14  [jsx-text]  "No sources found."
+src/components/AddSourceDialog.tsx:31:20  [jsx-attribute:placeholder]  "https://example.com/feed.xml"
+```
+
+## Programmatic
+
+```ts
+import { scanSource } from '@liam-public/node-i18n-lint'
+
+const findings = scanSource('SourcesPage.tsx', code)
+// [{ line, column, text, kind: 'jsx-text' | 'jsx-attribute' | 'jsx-expression', attribute? }]
+```
+
+`typescript` is a peer dependency (every TS project already has it).

package/dist/chunk-47SPJKTR.js

@@ -0,0 +1,62 @@
+// src/scan.ts
+import ts from "typescript";
+var USER_FACING_ATTRS = /* @__PURE__ */ new Set([
+  "placeholder",
+  "title",
+  "alt",
+  "aria-label",
+  "aria-placeholder",
+  "aria-description",
+  "label"
+]);
+var hasLetters = (s) => /\p{L}/u.test(s);
+function isTranslatable(raw) {
+  const s = raw.trim();
+  if (!s) return false;
+  if (!hasLetters(s)) return false;
+  if (/^https?:\/\//i.test(s)) return false;
+  if (/^[a-z][a-zA-Z0-9]*$/.test(s) && s.length <= 2) return false;
+  if (/^[#.][\w-]+$/.test(s)) return false;
+  return true;
+}
+function scanSource(fileName, code) {
+  const sf = ts.createSourceFile(fileName, code, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  const findings = [];
+  const ignoredLines = /* @__PURE__ */ new Set();
+  code.split("\n").forEach((lineText, i) => {
+    if (lineText.includes("i18n-ignore")) {
+      ignoredLines.add(i + 1);
+      ignoredLines.add(i + 2);
+    }
+  });
+  const at = (node) => {
+    const { line, character } = sf.getLineAndCharacterOfPosition(node.getStart(sf));
+    return { line: line + 1, column: character + 1 };
+  };
+  const push = (node, text, kind, attribute) => {
+    const loc = at(node);
+    if (ignoredLines.has(loc.line)) return;
+    findings.push({ ...loc, text: text.trim(), kind, attribute });
+  };
+  const visit = (node) => {
+    if (ts.isJsxText(node)) {
+      if (isTranslatable(node.text)) push(node, node.text, "jsx-text");
+    } else if (ts.isJsxAttribute(node) && node.initializer && ts.isStringLiteral(node.initializer)) {
+      const name = node.name.getText(sf);
+      if (USER_FACING_ATTRS.has(name) && isTranslatable(node.initializer.text)) {
+        push(node.initializer, node.initializer.text, "jsx-attribute", name);
+      }
+    } else if (ts.isJsxExpression(node) && node.expression && ts.isStringLiteralLike(node.expression) && isTranslatable(node.expression.text)) {
+      push(node.expression, node.expression.text, "jsx-expression");
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sf);
+  return findings;
+}
+
+export {
+  isTranslatable,
+  scanSource
+};
+//# sourceMappingURL=chunk-47SPJKTR.js.map

package/dist/chunk-47SPJKTR.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/scan.ts"],"sourcesContent":["import ts from 'typescript'\n\nexport type FindingKind = 'jsx-text' | 'jsx-attribute' | 'jsx-expression'\n\nexport interface Finding {\n  /** 1-based line. */\n  readonly line: number\n  /** 1-based column. */\n  readonly column: number\n  readonly text: string\n  readonly kind: FindingKind\n  /** Attribute name (for `jsx-attribute`). */\n  readonly attribute?: string\n}\n\n/** Attributes whose string-literal values are shown to users. */\nconst USER_FACING_ATTRS = new Set([\n  'placeholder',\n  'title',\n  'alt',\n  'aria-label',\n  'aria-placeholder',\n  'aria-description',\n  'label',\n])\n\nconst hasLetters = (s: string): boolean => /\\p{L}/u.test(s)\n\n/** Decide whether a literal is human-facing copy worth translating (vs. a token/number/url). */\nexport function isTranslatable(raw: string): boolean {\n  const s = raw.trim()\n  if (!s) return false\n  if (!hasLetters(s)) return false // numbers, punctuation, symbols only\n  if (/^https?:\\/\\//i.test(s)) return false // urls\n  if (/^[a-z][a-zA-Z0-9]*$/.test(s) && s.length <= 2) return false // tiny identifiers like \"px\"\n  if (/^[#.][\\w-]+$/.test(s)) return false // css selectors / hex-ish\n  return true\n}\n\n/** Scan a single TSX/JSX source string for hardcoded, untranslated strings. */\nexport function scanSource(fileName: string, code: string): Finding[] {\n  const sf = ts.createSourceFile(fileName, code, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX)\n  const findings: Finding[] = []\n\n  // Lines carrying an `i18n-ignore` directive are skipped.\n  const ignoredLines = new Set<number>()\n  code.split('\\n').forEach((lineText, i) => {\n    if (lineText.includes('i18n-ignore')) {\n      ignoredLines.add(i + 1)\n      ignoredLines.add(i + 2) // also the line after the comment\n    }\n  })\n\n  const at = (node: ts.Node) => {\n    const { line, character } = sf.getLineAndCharacterOfPosition(node.getStart(sf))\n    return { line: line + 1, column: character + 1 }\n  }\n  const push = (node: ts.Node, text: string, kind: FindingKind, attribute?: string) => {\n    const loc = at(node)\n    if (ignoredLines.has(loc.line)) return\n    findings.push({ ...loc, text: text.trim(), kind, attribute })\n  }\n\n  const visit = (node: ts.Node) => {\n    if (ts.isJsxText(node)) {\n      if (isTranslatable(node.text)) push(node, node.text, 'jsx-text')\n    } else if (ts.isJsxAttribute(node) && node.initializer && ts.isStringLiteral(node.initializer)) {\n      const name = node.name.getText(sf)\n      if (USER_FACING_ATTRS.has(name) && isTranslatable(node.initializer.text)) {\n        push(node.initializer, node.initializer.text, 'jsx-attribute', name)\n      }\n    } else if (\n      ts.isJsxExpression(node) &&\n      node.expression &&\n      ts.isStringLiteralLike(node.expression) &&\n      isTranslatable(node.expression.text)\n    ) {\n      // a bare string literal placed directly in JSX, e.g. {'Save'} or {`Hello`}\n      push(node.expression, node.expression.text, 'jsx-expression')\n    }\n    ts.forEachChild(node, visit)\n  }\n  visit(sf)\n  return findings\n}\n"],"mappings":";AAAA,OAAO,QAAQ;AAgBf,IAAM,oBAAoB,oBAAI,IAAI;AAAA,EAChC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAED,IAAM,aAAa,CAAC,MAAuB,SAAS,KAAK,CAAC;AAGnD,SAAS,eAAe,KAAsB;AACnD,QAAM,IAAI,IAAI,KAAK;AACnB,MAAI,CAAC,EAAG,QAAO;AACf,MAAI,CAAC,WAAW,CAAC,EAAG,QAAO;AAC3B,MAAI,gBAAgB,KAAK,CAAC,EAAG,QAAO;AACpC,MAAI,sBAAsB,KAAK,CAAC,KAAK,EAAE,UAAU,EAAG,QAAO;AAC3D,MAAI,eAAe,KAAK,CAAC,EAAG,QAAO;AACnC,SAAO;AACT;AAGO,SAAS,WAAW,UAAkB,MAAyB;AACpE,QAAM,KAAK,GAAG,iBAAiB,UAAU,MAAM,GAAG,aAAa,QAAQ,MAAM,GAAG,WAAW,GAAG;AAC9F,QAAM,WAAsB,CAAC;AAG7B,QAAM,eAAe,oBAAI,IAAY;AACrC,OAAK,MAAM,IAAI,EAAE,QAAQ,CAAC,UAAU,MAAM;AACxC,QAAI,SAAS,SAAS,aAAa,GAAG;AACpC,mBAAa,IAAI,IAAI,CAAC;AACtB,mBAAa,IAAI,IAAI,CAAC;AAAA,IACxB;AAAA,EACF,CAAC;AAED,QAAM,KAAK,CAAC,SAAkB;AAC5B,UAAM,EAAE,MAAM,UAAU,IAAI,GAAG,8BAA8B,KAAK,SAAS,EAAE,CAAC;AAC9E,WAAO,EAAE,MAAM,OAAO,GAAG,QAAQ,YAAY,EAAE;AAAA,EACjD;AACA,QAAM,OAAO,CAAC,MAAe,MAAc,MAAmB,cAAuB;AACnF,UAAM,MAAM,GAAG,IAAI;AACnB,QAAI,aAAa,IAAI,IAAI,IAAI,EAAG;AAChC,aAAS,KAAK,EAAE,GAAG,KAAK,MAAM,KAAK,KAAK,GAAG,MAAM,UAAU,CAAC;AAAA,EAC9D;AAEA,QAAM,QAAQ,CAAC,SAAkB;AAC/B,QAAI,GAAG,UAAU,IAAI,GAAG;AACtB,UAAI,eAAe,KAAK,IAAI,EAAG,MAAK,MAAM,KAAK,MAAM,UAAU;AAAA,IACjE,WAAW,GAAG,eAAe,IAAI,KAAK,KAAK,eAAe,GAAG,gBAAgB,KAAK,WAAW,GAAG;AAC9F,YAAM,OAAO,KAAK,KAAK,QAAQ,EAAE;AACjC,UAAI,kBAAkB,IAAI,IAAI,KAAK,eAAe,KAAK,YAAY,IAAI,GAAG;AACxE,aAAK,KAAK,aAAa,KAAK,YAAY,MAAM,iBAAiB,IAAI;AAAA,MACrE;AAAA,IACF,WACE,GAAG,gBAAgB,IAAI,KACvB,KAAK,cACL,GAAG,oBAAoB,KAAK,UAAU,KACtC,eAAe,KAAK,WAAW,IAAI,GACnC;AAEA,WAAK,KAAK,YAAY,KAAK,WAAW,MAAM,gBAAgB;AAAA,IAC9D;AACA,OAAG,aAAa,MAAM,KAAK;AAAA,EAC7B;AACA,QAAM,EAAE;AACR,SAAO;AACT;","names":[]}

package/dist/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/cli.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+import {
+  scanSource
+} from "./chunk-47SPJKTR.js";
+
+// src/cli.ts
+import { readFileSync, readdirSync, statSync } from "fs";
+import { extname, join } from "path";
+var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", "dist", "build", "coverage", ".git"]);
+var EXTS = /* @__PURE__ */ new Set([".tsx", ".jsx"]);
+function collect(path, out = []) {
+  const stat = statSync(path);
+  if (stat.isDirectory()) {
+    for (const entry of readdirSync(path)) {
+      if (SKIP_DIRS.has(entry) || entry.startsWith(".")) continue;
+      collect(join(path, entry), out);
+    }
+  } else if (EXTS.has(extname(path)) && !path.endsWith(".test.tsx")) {
+    out.push(path);
+  }
+  return out;
+}
+function main() {
+  const args = process.argv.slice(2);
+  const roots = args.length ? args : ["."];
+  const files = roots.flatMap((root) => collect(root));
+  let total = 0;
+  for (const file of files) {
+    const findings = scanSource(file, readFileSync(file, "utf8"));
+    for (const f of findings) {
+      const attr = f.attribute ? `:${f.attribute}` : "";
+      process.stdout.write(`${file}:${f.line}:${f.column}  [${f.kind}${attr}]  ${JSON.stringify(f.text)}
+`);
+    }
+    total += findings.length;
+  }
+  process.stderr.write(`
+${total} untranslated string(s) across ${files.length} file(s)
+`);
+  process.exit(total > 0 ? 1 : 0);
+}
+main();
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\nimport { readFileSync, readdirSync, statSync } from 'node:fs'\nimport { extname, join } from 'node:path'\nimport { scanSource } from './scan.js'\n\nconst SKIP_DIRS = new Set(['node_modules', 'dist', 'build', 'coverage', '.git'])\nconst EXTS = new Set(['.tsx', '.jsx'])\n\nfunction collect(path: string, out: string[] = []): string[] {\n  const stat = statSync(path)\n  if (stat.isDirectory()) {\n    for (const entry of readdirSync(path)) {\n      if (SKIP_DIRS.has(entry) || entry.startsWith('.')) continue\n      collect(join(path, entry), out)\n    }\n  } else if (EXTS.has(extname(path)) && !path.endsWith('.test.tsx')) {\n    out.push(path)\n  }\n  return out\n}\n\nfunction main(): void {\n  const args = process.argv.slice(2)\n  const roots = args.length ? args : ['.']\n  const files = roots.flatMap((root) => collect(root))\n\n  let total = 0\n  for (const file of files) {\n    const findings = scanSource(file, readFileSync(file, 'utf8'))\n    for (const f of findings) {\n      const attr = f.attribute ? `:${f.attribute}` : ''\n      process.stdout.write(`${file}:${f.line}:${f.column}  [${f.kind}${attr}]  ${JSON.stringify(f.text)}\\n`)\n    }\n    total += findings.length\n  }\n\n  process.stderr.write(`\\n${total} untranslated string(s) across ${files.length} file(s)\\n`)\n  process.exit(total > 0 ? 1 : 0)\n}\n\nmain()\n"],"mappings":";;;;;;AACA,SAAS,cAAc,aAAa,gBAAgB;AACpD,SAAS,SAAS,YAAY;AAG9B,IAAM,YAAY,oBAAI,IAAI,CAAC,gBAAgB,QAAQ,SAAS,YAAY,MAAM,CAAC;AAC/E,IAAM,OAAO,oBAAI,IAAI,CAAC,QAAQ,MAAM,CAAC;AAErC,SAAS,QAAQ,MAAc,MAAgB,CAAC,GAAa;AAC3D,QAAM,OAAO,SAAS,IAAI;AAC1B,MAAI,KAAK,YAAY,GAAG;AACtB,eAAW,SAAS,YAAY,IAAI,GAAG;AACrC,UAAI,UAAU,IAAI,KAAK,KAAK,MAAM,WAAW,GAAG,EAAG;AACnD,cAAQ,KAAK,MAAM,KAAK,GAAG,GAAG;AAAA,IAChC;AAAA,EACF,WAAW,KAAK,IAAI,QAAQ,IAAI,CAAC,KAAK,CAAC,KAAK,SAAS,WAAW,GAAG;AACjE,QAAI,KAAK,IAAI;AAAA,EACf;AACA,SAAO;AACT;AAEA,SAAS,OAAa;AACpB,QAAM,OAAO,QAAQ,KAAK,MAAM,CAAC;AACjC,QAAM,QAAQ,KAAK,SAAS,OAAO,CAAC,GAAG;AACvC,QAAM,QAAQ,MAAM,QAAQ,CAAC,SAAS,QAAQ,IAAI,CAAC;AAEnD,MAAI,QAAQ;AACZ,aAAW,QAAQ,OAAO;AACxB,UAAM,WAAW,WAAW,MAAM,aAAa,MAAM,MAAM,CAAC;AAC5D,eAAW,KAAK,UAAU;AACxB,YAAM,OAAO,EAAE,YAAY,IAAI,EAAE,SAAS,KAAK;AAC/C,cAAQ,OAAO,MAAM,GAAG,IAAI,IAAI,EAAE,IAAI,IAAI,EAAE,MAAM,MAAM,EAAE,IAAI,GAAG,IAAI,MAAM,KAAK,UAAU,EAAE,IAAI,CAAC;AAAA,CAAI;AAAA,IACvG;AACA,aAAS,SAAS;AAAA,EACpB;AAEA,UAAQ,OAAO,MAAM;AAAA,EAAK,KAAK,kCAAkC,MAAM,MAAM;AAAA,CAAY;AACzF,UAAQ,KAAK,QAAQ,IAAI,IAAI,CAAC;AAChC;AAEA,KAAK;","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,17 @@
+type FindingKind = 'jsx-text' | 'jsx-attribute' | 'jsx-expression';
+interface Finding {
+    /** 1-based line. */
+    readonly line: number;
+    /** 1-based column. */
+    readonly column: number;
+    readonly text: string;
+    readonly kind: FindingKind;
+    /** Attribute name (for `jsx-attribute`). */
+    readonly attribute?: string;
+}
+/** Decide whether a literal is human-facing copy worth translating (vs. a token/number/url). */
+declare function isTranslatable(raw: string): boolean;
+/** Scan a single TSX/JSX source string for hardcoded, untranslated strings. */
+declare function scanSource(fileName: string, code: string): Finding[];
+
+export { type Finding, type FindingKind, isTranslatable, scanSource };

package/dist/index.js

@@ -0,0 +1,9 @@
+import {
+  isTranslatable,
+  scanSource
+} from "./chunk-47SPJKTR.js";
+export {
+  isTranslatable,
+  scanSource
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@liam-public/node-i18n-lint",
+  "version": "0.1.0",
+  "description": "Detect hardcoded, untranslated strings in JSX/TSX — JSX text, user-facing attributes, and bare string literals — so you can wrap them in t().",
+  "type": "module",
+  "liamCompatibility": {
+    "runtime": [
+      "server"
+    ],
+    "framework": [
+      "agnostic"
+    ]
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "i18n-lint": "./dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts src/cli.ts --format esm --dts --sourcemap",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  }
+}