localization-drift 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 m1chlcz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,93 @@
+# localization-drift
+
+Fail a build when customer-visible text bypasses translation keys.
+
+## Features
+
+- Flags hardcoded JSX text and localized attributes in `.tsx` files.
+- Flags configured forbidden patterns in the scanned source files.
+- Honors a reviewed exception comment on the line before a finding.
+- Runs as a CLI, an npm package, or a GitHub Action.
+- Pairs with [localize](https://github.com/m1chlcz/localize) for the workbook and ARB side.
+
+## Install
+
+```
+npm install --save-dev localization-drift
+```
+
+Node.js 22 or later is required.
+
+## Usage
+
+```
+npx localization-drift
+npx localization-drift --root app --root components
+npx localization-drift --json
+```
+
+The output is one line per finding: `path:line: kind: message`. The exit code is 1 for findings and 2 for a usage or configuration error.
+
+## Configuration
+
+Create `localization-drift.json` in the repository root:
+
+```json
+{
+  "roots": ["app", "components"],
+  "extensions": [".tsx", ".ts"],
+  "attributes": ["alt", "aria-label", "placeholder", "title"],
+  "exclude": ["\\.test\\.", "/generated/", "node_modules"],
+  "forbidden": [
+    {
+      "pattern": "widget_type\\s*===\\s*[\"'][^\"']+[\"']",
+      "message": "use stored capabilities instead of a widget value"
+    }
+  ]
+}
+```
+
+| Field | Default | Meaning |
+| --- | --- | --- |
+| `roots` | `["src"]` | The directories to scan. |
+| `extensions` | `[".tsx", ".ts"]` | The file extensions to scan. |
+| `attributes` | `["alt", "aria-label", "placeholder", "title"]` | The JSX attributes that must use a key. |
+| `exclude` | tests, `/generated/`, `node_modules` | Regular expressions for paths to skip. |
+| `forbidden` | `[]` | Regular expression rules with a message. |
+| `allowComment` | the marker below | The exception marker prefix. |
+
+## Exception
+
+Put the marker and a reason on the line before the finding:
+
+```tsx
+// localization-drift: allow-next-line -- registered brand name
+<strong>WhatsApp</strong>
+```
+
+## GitHub Action
+
+```yaml
+- uses: actions/checkout@v7
+- uses: m1chlcz/localization-drift@v0.1.0
+  with:
+    args: --root app
+```
+
+Combine it with `localize` to catch generated-file drift as well:
+
+```yaml
+- run: go run github.com/m1chlcz/localize/cmd/localize@latest generate --input translations.xlsx --output-dir arb
+- run: git diff --exit-code -- arb
+```
+
+## Development
+
+```
+npm ci
+npm test
+```
+
+## License
+
+MIT. See `LICENSE`.

package/action.yml

@@ -0,0 +1,18 @@
+name: localization-drift
+description: Fail when customer-visible text bypasses translation keys.
+inputs:
+  args:
+    description: Extra arguments for the audit.
+    required: false
+    default: ""
+runs:
+  using: composite
+  steps:
+    - name: Install
+      shell: bash
+      run: npm ci --prefix "${{ github.action_path }}" --no-audit --no-fund
+    - name: Audit localization
+      shell: bash
+      env:
+        INPUT_ARGS: ${{ inputs.args }}
+      run: node "${{ github.action_path }}/src/cli.mjs" $INPUT_ARGS

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "localization-drift",
+  "version": "0.1.0",
+  "description": "Fail a build when customer-visible text bypasses translation keys.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/m1chlcz/localization-drift.git"
+  },
+  "homepage": "https://github.com/m1chlcz/localization-drift",
+  "bugs": "https://github.com/m1chlcz/localization-drift/issues",
+  "keywords": [
+    "i18n",
+    "localization",
+    "translation",
+    "lint",
+    "typescript",
+    "react",
+    "jsx",
+    "github-action"
+  ],
+  "bin": {
+    "localization-drift": "src/cli.mjs"
+  },
+  "exports": {
+    ".": "./src/index.mjs",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "action.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "dependencies": {
+    "typescript": "6.0.3"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+
+import { scanRepository } from "./index.mjs";
+
+const version = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+
+const usage = `Usage: localization-drift [options]
+
+Options:
+  --config FILE    read a JSON configuration file
+  --root DIR       scan DIR (repeatable; overrides the configured roots)
+  --json           print the findings as JSON
+  -h, --help       show this help
+  -v, --version    show the version`;
+
+function readConfig(path, required) {
+  if (!path) return {};
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (error) {
+    if (error.code === "ENOENT" && !required) return {};
+    if (error.code === "ENOENT") throw new Error(`configuration file not found: ${path}`);
+    throw new Error(`invalid configuration file: ${path}`);
+  }
+}
+
+async function main() {
+  const { values } = parseArgs({
+    args: process.argv.slice(2),
+    options: {
+      config: { type: "string" },
+      root: { type: "string", multiple: true },
+      json: { type: "boolean" },
+      help: { type: "boolean", short: "h" },
+      version: { type: "boolean", short: "v" },
+    },
+    strict: true,
+  });
+  if (values.version) {
+    process.stdout.write(`${version}\n`);
+    return;
+  }
+  if (values.help) {
+    process.stdout.write(`${usage}\n`);
+    return;
+  }
+
+  const root = process.cwd();
+  const config = values.config
+    ? readConfig(resolve(root, values.config), true)
+    : readConfig(resolve(root, "localization-drift.json"), false);
+  if (values.root?.length) config.roots = values.root;
+
+  const findings = await scanRepository(root, config);
+  if (values.json) {
+    process.stdout.write(`${JSON.stringify(findings, null, 2)}\n`);
+  } else if (findings.length === 0) {
+    process.stdout.write("Localization audit passed.\n");
+  } else {
+    for (const item of findings) {
+      process.stderr.write(`${item.path}:${item.line}: ${item.kind}: ${item.message}\n`);
+    }
+    process.stderr.write(`${findings.length} localization finding(s).\n`);
+  }
+  if (findings.length > 0) process.exitCode = 1;
+}
+
+main().catch((error) => {
+  process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+  process.exitCode = 2;
+});

package/src/index.mjs

@@ -0,0 +1,161 @@
+import { readFile, readdir } from "node:fs/promises";
+import { extname, join, relative, sep } from "node:path";
+import ts from "typescript";
+
+export const ALLOW_COMMENT = "// localization-drift: allow-next-line -- ";
+
+export const DEFAULT_CONFIG = Object.freeze({
+  roots: ["src"],
+  extensions: [".tsx", ".ts"],
+  attributes: ["alt", "aria-label", "placeholder", "title"],
+  exclude: ["\\.test\\.", "/test/", "/generated/", "node_modules", "\\.d\\.ts$"],
+  forbidden: [],
+});
+
+function lineDetails(source, index) {
+  const before = source.slice(0, index);
+  const line = before.split("\n").length;
+  const lines = source.split("\n");
+  return {
+    line,
+    text: lines[line - 1]?.trim() ?? "",
+    previous: lines[line - 2]?.trim() ?? "",
+  };
+}
+
+function reviewedException(source, index, allowComment) {
+  return lineDetails(source, index).previous.startsWith(allowComment);
+}
+
+function finding(path, source, index, kind, message) {
+  const details = lineDetails(source, index);
+  return { path, line: details.line, kind, message, text: details.text };
+}
+
+/**
+ * analyzeSource reports customer-visible JSX text, localized attributes, and
+ * configured forbidden patterns in one source file.
+ */
+export function analyzeSource(path, source, options = {}) {
+  const {
+    checkJSX = path.endsWith(".tsx"),
+    attributes = DEFAULT_CONFIG.attributes,
+    forbidden = [],
+    allowComment = ALLOW_COMMENT,
+  } = options;
+  const localizedAttributes = new Set(attributes);
+  const indexed = [];
+
+  if (checkJSX) {
+    const sourceFile = ts.createSourceFile(path, source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+    const visit = (node) => {
+      if (ts.isJsxAttribute(node) &&
+          localizedAttributes.has(node.name.text) &&
+          node.initializer && ts.isStringLiteral(node.initializer) &&
+          /\p{L}/u.test(node.initializer.text)) {
+        const index = node.getStart(sourceFile);
+        if (!reviewedException(source, index, allowComment)) {
+          indexed.push({
+            index,
+            finding: finding(
+              path,
+              source,
+              index,
+              "localized-attribute",
+              `customer-visible ${node.name.text} must come from a translation key`,
+            ),
+          });
+        }
+      }
+      if (ts.isJsxText(node)) {
+        const value = node.getText(sourceFile).replace(/\s+/g, " ").trim();
+        const index = node.getStart(sourceFile);
+        if (value && /\p{L}/u.test(value) && !reviewedException(source, index, allowComment)) {
+          indexed.push({
+            index,
+            finding: finding(
+              path,
+              source,
+              index,
+              "localized-jsx-text",
+              `customer-visible JSX text must come from a translation key: ${JSON.stringify(value)}`,
+            ),
+          });
+        }
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+  }
+
+  for (const rule of forbidden) {
+    if (!rule || typeof rule.pattern !== "string" || typeof rule.message !== "string") continue;
+    const pattern = new RegExp(rule.pattern, "g");
+    for (const match of source.matchAll(pattern)) {
+      if (reviewedException(source, match.index, allowComment)) continue;
+      indexed.push({
+        index: match.index,
+        finding: finding(path, source, match.index, "forbidden-pattern", rule.message),
+      });
+    }
+  }
+
+  return indexed
+    .sort((left, right) => left.index - right.index)
+    .map(({ finding: result }) => result);
+}
+
+function excludedPath(path, exclude) {
+  return exclude.some((pattern) => new RegExp(pattern).test(path));
+}
+
+async function* walk(directory, config) {
+  let entries;
+  try {
+    entries = await readdir(directory, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    if ([".git", ".next", ".tmp", "node_modules"].includes(entry.name)) continue;
+    const path = join(directory, entry.name);
+    if (entry.isDirectory()) {
+      yield* walk(path, config);
+      continue;
+    }
+    if (!config.extensions.includes(extname(entry.name))) continue;
+    yield path;
+  }
+}
+
+/**
+ * scanRepository walks the configured roots and returns every finding, sorted
+ * by path and line.
+ */
+export async function scanRepository(root, config = {}) {
+  const settings = {
+    roots: config.roots ?? DEFAULT_CONFIG.roots,
+    extensions: config.extensions ?? DEFAULT_CONFIG.extensions,
+    attributes: config.attributes ?? DEFAULT_CONFIG.attributes,
+    exclude: config.exclude ?? DEFAULT_CONFIG.exclude,
+    forbidden: config.forbidden ?? DEFAULT_CONFIG.forbidden,
+    allowComment: config.allowComment ?? ALLOW_COMMENT,
+  };
+  const findings = [];
+  for (const directory of settings.roots) {
+    for await (const absolute of walk(join(root, directory), settings)) {
+      const path = relative(root, absolute).split(sep).join("/");
+      if (excludedPath(path, settings.exclude)) continue;
+      const source = await readFile(absolute, "utf8");
+      findings.push(...analyzeSource(path, source, {
+        checkJSX: settings.extensions.includes(extname(path)) && path.endsWith(".tsx"),
+        attributes: settings.attributes,
+        forbidden: settings.forbidden,
+        allowComment: settings.allowComment,
+      }));
+    }
+  }
+  return findings.sort((left, right) =>
+    left.path.localeCompare(right.path) || left.line - right.line
+  );
+}