i18n-smell-detector 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,131 @@
+# i18n-smell-detector
+
+`i18n-smell-detector` identifies potential "stale" translations in your localization files. It flags keys where the translated value is identical to the base locale, which often indicates that a string was never actually translated.
+
+## Features
+
+- Smart Detection: Categorizes identical translations based on length and content (words vs. phrases).
+
+- Flexible Whitelisting: Exclude brand names, protocol codes, or common UI labels via configuration.
+
+- CI Integration: Configurable failure thresholds (`fail-on`) for build pipelines.
+
+- Multiple Output Formats: Supports console, JSON, and Markdown.
+
+
+## Install
+
+```bash
+npm install -D i18n-smell-detector
+```
+
+For local development:
+
+```bash
+npm install
+npm test
+npm run check
+```
+
+## Usage
+
+Run the check:
+
+```bash
+npx i18n-smell-detector check-identical --config i18n-smell.config.mjs
+```
+
+Output Options:
+
+```bash
+# Default output is console
+npx i18n-smell-detector check-identical --format console
+npx i18n-smell-detector check-identical --format json
+npx i18n-smell-detector check-identical --format markdown
+```
+
+### CI/CD Integration
+
+Set the severity level that causes the process to exit with an error:
+
+```bash
+npx i18n-smell-detector check-identical --fail-on high
+npx i18n-smell-detector check-identical --fail-on medium
+npx i18n-smell-detector check-identical --fail-on none
+```
+
+## Configuration(`i18n-smell.config.mjs`)
+
+```js
+export default {
+  baseLocale: 'en',
+  locales: {
+    en: './src/locales/en.json',
+    zh: './src/locales/zh.json',
+    ja: './src/locales/ja.json',
+    ko: './src/locales/ko.json',
+    fr: './src/locales/fr.json',
+    // ...
+  },
+
+  // Whitelist specific keys
+  allowIdenticalKeys: [
+    'brand.*',
+    'protocol.*',
+    'common.ok',
+    'common.id'
+  ],
+  
+  // Whitelist specific values
+  allowIdenticalValues: [
+    'OK',
+    'ID',
+    'HTTP',
+    'API',
+    'GET',
+    'POST'
+  ],
+
+  ignoreSameLanguageFamily: true, // Ignore en -> en-GB
+  trimWhitespace: true, // Trim and compare
+  failOn: 'high'
+};
+```
+
+## Example output
+
+```txt
+i18n-smell-detector: identical translations
+high=2 medium=1 low=0 ignored=16
+
+HIGH zh.home.welcome
+  value: "Welcome back"
+  reason: copied English phrase
+
+HIGH zh.settings.profile
+  value: "Profile settings"
+  reason: copied English phrase
+
+MEDIUM ja.form.search
+  value: "Search"
+  reason: copied English word
+```
+
+## Detection Rules
+
+| Case | Level |
+|---|---|
+| Key matches `allowIdenticalKeys` | ignored |
+| Value matches `allowIdenticalValues` | ignored |
+| Same language family (e.g., en, en-GB) | ignored |
+| URLs, path, color, or code-like value | ignored |
+| Placeholder-only value (e.g., `{count}`) | ignored |
+| Short common label | low |
+| Single English word | medium |
+| English phrase | high |
+
+## Notes
+
+- ***Not a coverage checker***: This tool only reports keys that exist in both files but have identical values; it does not check for missing keys.
+
+- ***Conservative by design***: The rules are conservative. Tune `allowIdenticalKeys` and `allowIdenticalValues` before making this a mandatory step in your CI pipeline.

package/bin/i18n-smell-detector.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+import { runCli } from '../src/cli.js';
+
+runCli(process.argv).catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`i18n-smell-detector: ${message}`);
+  process.exit(2);
+});

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "i18n-smell-detector",
+  "version": "0.1.0",
+  "description": "Find locale values copied from the base locale.",
+  "type": "module",
+  "bin": {
+    "i18n-smell-detector": "./bin/i18n-smell-detector.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check": "node ./bin/i18n-smell-detector.js check-identical --config ./examples/vue-vite/i18n-smell.config.mjs",
+    "test": "node --test"
+  },
+  "keywords": [
+    "i18n",
+    "l10n",
+    "locale",
+    "translation",
+    "cli"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18.17"
+  }
+}

package/src/check-identical.js

@@ -0,0 +1,53 @@
+import { classifyIdentical } from './rules/classify-identical.js';
+
+function normalize(value, config) {
+  let text = String(value);
+  if (config.trimWhitespace ?? true) text = text.trim();
+  if (config.ignoreCase ?? false) text = text.toLowerCase();
+  return text;
+}
+
+/**
+ * @param {Record<string, Record<string, string>>} locales
+ * @param {import('./types.js').DetectorConfig} config
+ * @returns {import('./types.js').IdenticalIssue[]}
+ */
+export function checkIdenticalTranslations(locales, config) {
+  const base = locales[config.baseLocale];
+  const issues = [];
+
+  for (const [targetLocale, target] of Object.entries(locales)) {
+    if (targetLocale === config.baseLocale) continue;
+
+    for (const [key, baseValue] of Object.entries(base)) {
+      if (!(key in target)) continue;
+      if (normalize(baseValue, config) !== normalize(target[key], config)) continue;
+
+      const { severity, reason } = classifyIdentical({
+        key,
+        value: target[key],
+        baseLocale: config.baseLocale,
+        targetLocale,
+        config,
+      });
+
+      issues.push({
+        key,
+        baseLocale: config.baseLocale,
+        targetLocale,
+        value: target[key],
+        severity,
+        reason,
+      });
+    }
+  }
+
+  return issues.sort(compareIssues);
+}
+
+function compareIssues(a, b) {
+  const rank = { high: 3, medium: 2, low: 1, ignored: 0 };
+  return rank[b.severity] - rank[a.severity]
+    || a.targetLocale.localeCompare(b.targetLocale)
+    || a.key.localeCompare(b.key);
+}

package/src/cli.js

@@ -0,0 +1,90 @@
+import path from 'node:path';
+import { checkIdenticalTranslations } from './check-identical.js';
+import { loadConfig, resolveConfigPath } from './config.js';
+import { loadFlattenedLocales } from './locale/load-locales.js';
+import { renderReport } from './reporters/index.js';
+import { failRank, severityRank } from './severity.js';
+
+const HELP = `
+i18n-smell-detector v0.1
+
+Usage:
+  i18n-smell-detector check-identical [options]
+  i18n-smell-detector check [options]
+
+Options:
+  -c, --config <path>       Config file path
+  --format <format>         console | json | markdown  (default: console)
+  --fail-on <level>         high | medium | low | none (default: config.failOn or high)
+  --include-ignored         Print ignored matches as well
+  -h, --help                Show help
+
+Example:
+  i18n-smell-detector check-identical -c i18n-smell.config.mjs --format markdown
+`;
+
+function parseArgs(argv) {
+  const args = argv.slice(2);
+  const command = args[0] && !args[0].startsWith('-') ? args.shift() : 'check-identical';
+  const options = { command, format: 'console', includeIgnored: false, help: false };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (arg === '-h' || arg === '--help') {
+      options.help = true;
+    } else if (arg === '-c' || arg === '--config') {
+      options.configPath = args[++index];
+    } else if (arg === '--format') {
+      options.format = readChoice(args[++index], ['console', 'json', 'markdown'], 'format');
+    } else if (arg === '--fail-on') {
+      options.failOn = readChoice(args[++index], ['none', 'low', 'medium', 'high'], 'fail-on level');
+    } else if (arg === '--include-ignored') {
+      options.includeIgnored = true;
+    } else {
+      throw new Error(`Unknown option: ${arg}`);
+    }
+  }
+
+  return options;
+}
+
+function readChoice(value, choices, name) {
+  if (!choices.includes(value)) {
+    throw new Error(`Unsupported ${name}: ${value}`);
+  }
+  return value;
+}
+
+export async function runCli(argv) {
+  const options = parseArgs(argv);
+
+  if (options.help || options.command === 'help') {
+    console.log(HELP.trim());
+    return;
+  }
+
+  if (!['check-identical', 'check'].includes(options.command)) {
+    throw new Error(`Unknown command: ${options.command}\n${HELP}`);
+  }
+
+  const configPath = await resolveConfigPath(options.configPath, process.cwd());
+  const config = await loadConfig(configPath);
+  const effectiveConfig = {
+    ...config,
+    failOn: options.failOn || config.failOn || 'high',
+    includeIgnored: options.includeIgnored || config.includeIgnored || false,
+  };
+
+  const locales = await loadFlattenedLocales(effectiveConfig, path.dirname(configPath));
+  const issues = checkIdenticalTranslations(locales, effectiveConfig);
+
+  console.log(renderReport(issues, {
+    format: options.format,
+    includeIgnored: effectiveConfig.includeIgnored || false,
+  }));
+
+  const visible = effectiveConfig.includeIgnored ? issues : issues.filter((issue) => issue.severity !== 'ignored');
+  const shouldFail = visible.some((issue) => severityRank[issue.severity] >= failRank(effectiveConfig.failOn || 'high'));
+  if (shouldFail) process.exit(1);
+}

package/src/config.js

@@ -0,0 +1,86 @@
+import { access } from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+const CONFIG_FILES = [
+  'i18n-smell.config.mjs',
+  'i18n-smell.config.cjs',
+  'i18n-smell.config.js',
+  'i18n-smell.config.json',
+];
+
+async function exists(filePath) {
+  try {
+    await access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export async function resolveConfigPath(explicitPath, cwd) {
+  if (explicitPath) {
+    const absolute = path.isAbsolute(explicitPath) ? explicitPath : path.resolve(cwd, explicitPath);
+    if (!(await exists(absolute))) throw new Error(`Config file not found: ${absolute}`);
+    return absolute;
+  }
+
+  for (const file of CONFIG_FILES) {
+    const absolute = path.resolve(cwd, file);
+    if (await exists(absolute)) return absolute;
+  }
+
+  throw new Error(`Config file not found. Expected one of: ${CONFIG_FILES.join(', ')}`);
+}
+
+export async function loadConfig(configPath) {
+  let loaded;
+
+  if (configPath.endsWith('.json') || configPath.endsWith('.cjs')) {
+    loaded = require(configPath);
+  } else {
+    loaded = await import(pathToFileURL(configPath).href);
+  }
+
+  const config = loaded.default || loaded;
+  validateConfig(config);
+  return withDefaults(config);
+}
+
+function validateConfig(config) {
+  if (!config || typeof config !== 'object') {
+    throw new Error('Config must export an object');
+  }
+
+  const candidate = /** @type {Record<string, unknown>} */ (config);
+  if (typeof candidate.baseLocale !== 'string' || !candidate.baseLocale) {
+    throw new Error('Config must include baseLocale');
+  }
+
+  if (!candidate.locales || typeof candidate.locales !== 'object' || Array.isArray(candidate.locales)) {
+    throw new Error('Config must include locales as an object');
+  }
+
+  for (const [locale, value] of Object.entries(candidate.locales)) {
+    if (typeof value !== 'string' || !value) {
+      throw new Error(`Config locales.${locale} must be a file path string`);
+    }
+  }
+}
+
+/** @param {import('./types.js').DetectorConfig} config */
+function withDefaults(config) {
+  return {
+    allowIdenticalKeys: [],
+    allowIdenticalValues: [],
+    ignoreSameLanguageFamily: true,
+    trimWhitespace: true,
+    ignoreCase: false,
+    includeIgnored: false,
+    failOn: 'high',
+    ...config,
+  };
+}

package/src/locale/flatten-locale.js

@@ -0,0 +1,28 @@
+/**
+ * @param {unknown} input
+ * @param {string} [prefix]
+ * @returns {Record<string, string>}
+ */
+export function flattenLocale(input, prefix = '') {
+  const result = {};
+
+  if (typeof input === 'string') {
+    if (prefix) result[prefix] = input;
+    return result;
+  }
+
+  if (Array.isArray(input)) {
+    input.forEach((value, index) => {
+      Object.assign(result, flattenLocale(value, prefix ? `${prefix}.${index}` : String(index)));
+    });
+    return result;
+  }
+
+  if (!input || typeof input !== 'object') return result;
+
+  for (const [key, value] of Object.entries(input)) {
+    Object.assign(result, flattenLocale(value, prefix ? `${prefix}.${key}` : key));
+  }
+
+  return result;
+}

package/src/locale/load-locales.js

@@ -0,0 +1,32 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { flattenLocale } from './flatten-locale.js';
+
+async function readJson(filePath) {
+  const text = await readFile(filePath, 'utf8');
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(`Failed to parse ${filePath}: ${message}`);
+  }
+}
+
+/**
+ * @param {import('../types.js').DetectorConfig} config
+ * @param {string} cwd
+ */
+export async function loadFlattenedLocales(config, cwd) {
+  const locales = {};
+
+  for (const [locale, localePath] of Object.entries(config.locales || {})) {
+    const absolutePath = path.isAbsolute(localePath) ? localePath : path.resolve(cwd, localePath);
+    locales[locale] = flattenLocale(await readJson(absolutePath));
+  }
+
+  if (!locales[config.baseLocale]) {
+    throw new Error(`baseLocale "${config.baseLocale}" is not listed in config.locales`);
+  }
+
+  return locales;
+}

package/src/reporters/console.js

@@ -0,0 +1,49 @@
+function color(code, text) {
+  if (process.env.NO_COLOR) return text;
+  return `\u001b[${code}m${text}\u001b[0m`;
+}
+
+function label(level) {
+  if (level === 'high') return color('31;1', 'HIGH');
+  if (level === 'medium') return color('33;1', 'MEDIUM');
+  if (level === 'low') return color('36;1', 'LOW');
+  return color('90', 'IGNORED');
+}
+
+function preview(value) {
+  const text = value.replace(/\s+/g, ' ').trim();
+  return text.length <= 90 ? text : `${text.slice(0, 87)}...`;
+}
+
+export function renderConsoleReport(issues, options) {
+  const visible = options.includeIgnored ? issues : issues.filter((issue) => issue.severity !== 'ignored');
+  const counts = countBySeverity(issues);
+  const lines = [
+    color('1', 'i18n-smell-detector: identical translations'),
+    `high=${counts.high} medium=${counts.medium} low=${counts.low} ignored=${counts.ignored}`,
+  ];
+
+  if (visible.length === 0) {
+    lines.push(color('32', 'No copied base-locale values found.'));
+    return lines.join('\n');
+  }
+
+  lines.push('');
+  for (const issue of visible) {
+    lines.push(`${label(issue.severity)} ${issue.targetLocale}.${issue.key}`);
+    lines.push(`  value: "${preview(issue.value)}"`);
+    lines.push(`  reason: ${issue.reason}`);
+  }
+
+  return lines.join('\n');
+}
+
+function countBySeverity(issues) {
+  return issues.reduce(
+    (acc, issue) => {
+      acc[issue.severity] += 1;
+      return acc;
+    },
+    { high: 0, medium: 0, low: 0, ignored: 0 }
+  );
+}

package/src/reporters/index.js

@@ -0,0 +1,9 @@
+import { renderConsoleReport } from './console.js';
+import { renderJsonReport } from './json.js';
+import { renderMarkdownReport } from './markdown.js';
+
+export function renderReport(issues, options) {
+  if (options.format === 'json') return renderJsonReport(issues, options);
+  if (options.format === 'markdown') return renderMarkdownReport(issues, options);
+  return renderConsoleReport(issues, options);
+}

package/src/reporters/json.js

@@ -0,0 +1,4 @@
+export function renderJsonReport(issues, options) {
+  const visible = options.includeIgnored ? issues : issues.filter((issue) => issue.severity !== 'ignored');
+  return `${JSON.stringify({ issues: visible }, null, 2)}\n`;
+}

package/src/reporters/markdown.js

@@ -0,0 +1,23 @@
+function escapeCell(value) {
+  return String(value).replace(/\|/g, '\\|').replace(/\n/g, '<br>');
+}
+
+export function renderMarkdownReport(issues, options) {
+  const visible = options.includeIgnored ? issues : issues.filter((issue) => issue.severity !== 'ignored');
+  const lines = ['# Identical translations', ''];
+
+  if (visible.length === 0) {
+    lines.push('No copied base-locale values found.');
+    return `${lines.join('\n')}\n`;
+  }
+
+  lines.push('| Level | Locale | Key | Value | Reason |');
+  lines.push('|---|---|---|---|---|');
+  for (const issue of visible) {
+    lines.push(
+      `| ${escapeCell(issue.severity)} | ${escapeCell(issue.targetLocale)} | ${escapeCell(issue.key)} | ${escapeCell(issue.value)} | ${escapeCell(issue.reason)} |`
+    );
+  }
+
+  return `${lines.join('\n')}\n`;
+}

package/src/rules/classify-identical.js

@@ -0,0 +1,82 @@
+import { matchesAnyPattern } from './match-pattern.js';
+
+function isBlank(value) {
+  return value.trim().length === 0;
+}
+
+function isExternalReference(value) {
+  const text = value.trim();
+  return /^(https?:\/\/|tel:)/i.test(text) || /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(text);
+}
+
+function isCodeLike(value) {
+  const text = value.trim();
+  return /^#[0-9a-f]{3,8}$/i.test(text)
+    || /^\/[a-z0-9_./:-]*$/i.test(text)
+    || /^[A-Z]{2,5}$/.test(text)
+    || /^[A-Z]{2,5}\s?[0-9A-Z-]*$/.test(text)
+    || (/^[a-z0-9_.:-]+$/.test(text) && !/\s/.test(text) && !/[A-Z]/.test(text));
+}
+
+function isPlaceholderOnly(value) {
+  const text = value
+    .replace(/\{\{\s*[^}]+\s*\}\}/g, '')
+    .replace(/\{\s*[^}]+\s*\}/g, '')
+    .replace(/[\s\p{P}\p{S}]/gu, '');
+  return text.length === 0;
+}
+
+function getLatinWords(value) {
+  return value.match(/[A-Za-z][A-Za-z']*/g) || [];
+}
+
+function languageFamily(locale) {
+  return locale.toLowerCase().split(/[-_]/)[0];
+}
+
+function isShortCommonLabel(value) {
+  const text = value.trim();
+  return text.length <= 3 || /^(ok|id|no|yes|on|off|5g|4g|lte)$/i.test(text);
+}
+
+/**
+ * @param {Object} input
+ * @param {string} input.key
+ * @param {string} input.value
+ * @param {string} input.baseLocale
+ * @param {string} input.targetLocale
+ * @param {import('../types.js').DetectorConfig} input.config
+ * @returns {{ severity: import('../types.js').Severity, reason: string }}
+ */
+export function classifyIdentical({ key, value, baseLocale, targetLocale, config }) {
+  if ((config.ignoreSameLanguageFamily ?? true) && languageFamily(baseLocale) === languageFamily(targetLocale)) {
+    return { severity: 'ignored', reason: 'same language family' };
+  }
+
+  if (matchesAnyPattern(key, config.allowIdenticalKeys || [])) {
+    return { severity: 'ignored', reason: 'allowed key' };
+  }
+
+  if ((config.allowIdenticalValues || []).includes(value)) {
+    return { severity: 'ignored', reason: 'allowed value' };
+  }
+
+  if (isBlank(value)) return { severity: 'ignored', reason: 'blank value' };
+  if (isExternalReference(value)) return { severity: 'ignored', reason: 'external reference' };
+  if (isPlaceholderOnly(value)) return { severity: 'ignored', reason: 'placeholder only' };
+  if (isCodeLike(value)) return { severity: 'ignored', reason: 'code-like value' };
+  if (isShortCommonLabel(value)) return { severity: 'low', reason: 'short common label' };
+
+  const words = getLatinWords(value);
+  const hasSentencePunctuation = /[.!?。！？]/.test(value);
+
+  if (words.length >= 2 || (words.length === 1 && hasSentencePunctuation)) {
+    return { severity: 'high', reason: 'copied English phrase' };
+  }
+
+  if (words.length === 1) {
+    return { severity: 'medium', reason: 'copied English word' };
+  }
+
+  return { severity: 'low', reason: 'same text as base locale' };
+}

package/src/rules/match-pattern.js

@@ -0,0 +1,8 @@
+function patternToRegExp(pattern) {
+  const escaped = pattern.replace(/[.+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`^${escaped.replace(/\*/g, '.*')}$`);
+}
+
+export function matchesAnyPattern(value, patterns = []) {
+  return patterns.some((pattern) => patternToRegExp(pattern).test(value));
+}

package/src/severity.js

@@ -0,0 +1,10 @@
+export const severityRank = {
+  ignored: 0,
+  low: 1,
+  medium: 2,
+  high: 3,
+};
+
+export function failRank(failOn) {
+  return failOn === 'none' ? Number.POSITIVE_INFINITY : severityRank[failOn];
+}

package/src/types.js

@@ -0,0 +1,25 @@
+/**
+ * @typedef {'ignored' | 'low' | 'medium' | 'high'} Severity
+ * @typedef {'console' | 'json' | 'markdown'} ReportFormat
+ *
+ * @typedef {Object} DetectorConfig
+ * @property {string} baseLocale
+ * @property {Record<string, string>} locales
+ * @property {string[]=} allowIdenticalKeys
+ * @property {string[]=} allowIdenticalValues
+ * @property {boolean=} ignoreSameLanguageFamily
+ * @property {boolean=} trimWhitespace
+ * @property {boolean=} ignoreCase
+ * @property {boolean=} includeIgnored
+ * @property {'none' | 'low' | 'medium' | 'high'=} failOn
+ *
+ * @typedef {Object} IdenticalIssue
+ * @property {string} key
+ * @property {string} baseLocale
+ * @property {string} targetLocale
+ * @property {string} value
+ * @property {Severity} severity
+ * @property {string} reason
+ */
+
+export {};