test: improve translation validation and linting system

.github/workflows/code-qa.yml

@@ -44,7 +44,7 @@ jobs:
       - name: Install dependencies
         run: npm run install:all
       - name: Verify all translations are complete
-        run: node scripts/find-missing-translations.js
+        run: npx jest --verbose locales/__tests__/lint-translations.test.ts locales/__tests__/find-missing-i18n-keys.test.ts
 
   knip:
     runs-on: ubuntu-latest

.roo/rules-translate/001-general-rules.md

@@ -88,11 +88,87 @@
 - Watch for placeholders and preserve them in translations
 - Be mindful of text length in UI elements when translating to languages that might require more characters
 - Use context-aware translations when the same string has different meanings
-- Always validate your translation work by running the missing translations script:
+- Always validate your translation work by running the translation tests:
     ```
-    node scripts/find-missing-translations.js
+    npx jest --verbose locales/__tests__/lint-translations.test.ts locales/__tests__/find-missing-i18n-keys.test.ts
     ```
-- Address any missing translations identified by the script to ensure complete coverage across all locales
+- Address any missing translations identified by the tests by using `node scripts/manage-translations.js` to ensure complete coverage across all locales:
+
+```sh
+./scripts/manage-translations.js
+Usage:
+Command Line Mode:
+  Add/update translations:
+    node scripts/manage-translations.js [-v] TRANSLATION_FILE KEY_PATH VALUE [KEY_PATH VALUE...]
+  Delete translations:
+    node scripts/manage-translations.js [-v] -d TRANSLATION_FILE1 [TRANSLATION_FILE2 ...] [ -- KEY1 ...]
+
+Key Path Format:
+  - Use single dot (.) for nested paths: 'command.newTask.title'
+  - Use double dots (..) to include a literal dot in key names (like SMTP byte stuffing):
+    'settings..path' -> { 'settings.path': 'value' }
+
+  Examples:
+    'command.newTask.title'     -> { command: { newTask: { title: 'value' } } }
+    'settings..path'            -> { 'settings.path': 'value' }
+    'nested.key..with..dots'    -> { nested: { 'key.with.dots': 'value' } }
+
+Line-by-Line JSON Mode (--stdin):
+  Each line must be a complete, single JSON object/array
+  Multi-line or combined JSON is not supported
+
+  Add/update translations:
+    node scripts/manage-translations.js [-v] --stdin TRANSLATION_FILE
+    Format: One object per line with exactly one key-value pair:
+      {"command.newTask.title": "New Task"}
+      {"settings..path": "Custom Path"}
+      {"nested.key..with..dots": "Value with dots in key"}
+
+  Delete translations:
+    node scripts/manage-translations.js [-v] -d --stdin TRANSLATION_FILE
+    Format: One array per line with exactly one key:
+      ["command.newTask.title"]
+      ["settings..path"]
+      ["nested.key..with..dots"]
+
+Options:
+  -v        Enable verbose output (shows operations)
+  -d        Delete mode - remove keys instead of setting them
+  --stdin   Read line-by-line JSON from stdin
+
+Examples:
+  # Add via command line, it is recommended to execute multiple translations simultaneously.
+  # The script expects a single file at a time with multiple key-value pairs, not multiple files.
+  node scripts/manage-translations.js package.nls.json command.newTask.title "New Task" [ key2 translation2 ... ] && \
+    node scripts/manage-translations.js package.nls.json settings..path "Custom Path" && \
+    node scripts/manage-translations.js package.nls.json nested.key..with..dots "Value with dots"
+
+  # Add multiple translations (one JSON object per line):
+  translations.txt:
+    {"command.newTask.title": "New Task"}
+    {"settings..path": "Custom Path"}
+    node scripts/manage-translations.js --stdin package.nls.json < translations.txt
+
+  # Delete multiple keys (one JSON array per line):
+  delete_keys.txt:
+    ["command.newTask.title"]
+    ["settings..path"]
+    ["nested.key..with..dots"]
+    node scripts/manage-translations.js -d --stdin package.nls.json < delete_keys.txt
+
+  # Using here document for batching:
+  node scripts/manage-translations.js --stdin package.nls.json << EOF
+    {"command.newTask.title": "New Task"}
+    {"settings..path": "Custom Path"}
+  EOF
+
+  # Delete using here document:
+  node scripts/manage-translations.js -d --stdin package.nls.json << EOF
+    ["command.newTask.title"]
+    ["settings..path"]
+    ["nested.key..with..dots"]
+  EOF
+```
 
 # 9. TRANSLATOR'S CHECKLIST
 

jest.config.js

@@ -41,7 +41,7 @@ module.exports = {
 	transformIgnorePatterns: [
 		"node_modules/(?!(@modelcontextprotocol|delay|p-wait-for|serialize-error|strip-ansi|default-shell|os-name|strip-bom)/)",
 	],
-	roots: ["<rootDir>/src", "<rootDir>/webview-ui/src"],
+	roots: ["<rootDir>/src", "<rootDir>/webview-ui/src", "<rootDir>/locales", "<rootDir>/scripts"],
 	modulePathIgnorePatterns: [".vscode-test"],
 	reporters: [["jest-simple-dot-reporter", {}]],
 	setupFiles: ["<rootDir>/src/__mocks__/jest.setup.ts"],

locales/__tests__/find-missing-i18n-keys.test.ts

@@ -0,0 +1,221 @@
+const fs = require("fs")
+const path = require("path")
+import {
+	languages,
+	bufferLog,
+	printLogs,
+	clearLogs,
+	fileExists,
+	loadFileContent,
+	parseJsonContent,
+	getValueAtPath,
+} from "./utils"
+
+// findMissingI18nKeys: Directories to traverse and their corresponding locales
+const SCAN_SOURCE_DIRS = {
+	components: {
+		path: "webview-ui/src/components",
+		localesDir: "webview-ui/src/i18n/locales",
+	},
+	src: {
+		path: "src",
+		localesDir: "src/i18n/locales",
+	},
+}
+
+// i18n key patterns for findMissingI18nKeys
+const i18nScanPatterns = [
+	/{t\("([^"]+)"\)}/g,
+	/i18nKey="([^"]+)"/g,
+	/t\("([a-zA-Z][a-zA-Z0-9_]*[:.][a-zA-Z0-9_.]+)"\)/g,
+]
+
+// Check if the key exists in all official language files, return a list of missing language files
+function checkKeyInLocales(key: string, localesDir: string): Array<[string, boolean]> {
+	const [file, ...pathParts] = key.split(":")
+	const jsonPath = pathParts.join(".")
+	const missingLocales = new Map<string, boolean>() // true = file missing, false = key missing
+
+	// Check all official languages including English
+	languages.forEach((locale) => {
+		const filePath = path.join(localesDir, locale, `${file}.json`)
+		const localePath = `${locale}/${file}.json`
+
+		// If file doesn't exist or can't be loaded, mark entire file as missing
+		if (!fileExists(filePath)) {
+			missingLocales.set(localePath, true)
+			return
+		}
+
+		const content = loadFileContent(filePath)
+		if (!content) {
+			missingLocales.set(localePath, true)
+			return
+		}
+
+		const json = parseJsonContent(content, filePath)
+		if (!json) {
+			missingLocales.set(localePath, true)
+			return
+		}
+
+		// Only check for missing key if file exists and is valid
+		if (getValueAtPath(json, jsonPath) === undefined) {
+			missingLocales.set(localePath, false)
+		}
+	})
+
+	return Array.from(missingLocales.entries())
+}
+
+// Recursively traverse the directory
+export function findMissingI18nKeys(): { output: string } {
+	clearLogs() // Clear buffer at start
+	let results: Array<{ key: string; file: string; missingLocales: Array<{ path: string; isFileMissing: boolean }> }> =
+		[]
+
+	function walk(dir: string, baseDir: string, localesDir: string) {
+		const files = fs.readdirSync(dir)
+
+		for (const file of files) {
+			const filePath = path.join(dir, file)
+			const stat = fs.statSync(filePath)
+
+			// Exclude test files and __mocks__ directory
+			if (filePath.includes(".test.") || filePath.includes("__mocks__")) continue
+
+			if (stat.isDirectory()) {
+				walk(filePath, baseDir, localesDir) // Recursively traverse subdirectories
+			} else if (stat.isFile() && [".ts", ".tsx", ".js", ".jsx"].includes(path.extname(filePath))) {
+				const relPath = path.relative(process.cwd(), filePath)
+				const content = fs.readFileSync(filePath, "utf8")
+
+				// Match all i18n keys
+				const matches = new Set<string>()
+				for (const pattern of i18nScanPatterns) {
+					let match
+					while ((match = pattern.exec(content)) !== null) {
+						matches.add(match[1])
+					}
+				}
+
+				// Check each unique key against all official languages
+				matches.forEach((key) => {
+					const missingLocales = checkKeyInLocales(key, localesDir)
+					if (missingLocales.length > 0) {
+						results.push({
+							key,
+							missingLocales: missingLocales.map(([locale, isFileMissing]) => ({
+								path: path.join(path.relative(process.cwd(), localesDir), locale),
+								isFileMissing,
+							})),
+							file: relPath,
+						})
+					}
+				})
+			}
+		}
+	}
+
+	// Walk through all directories and check against official languages
+	Object.entries(SCAN_SOURCE_DIRS).forEach(([_name, config]) => {
+		// Create locales directory if it doesn't exist
+		if (!fs.existsSync(config.localesDir)) {
+			bufferLog(`Warning: Creating missing locales directory: ${config.localesDir}`)
+			fs.mkdirSync(config.localesDir, { recursive: true })
+		}
+		walk(config.path, config.path, config.localesDir)
+	})
+
+	// Process results
+	bufferLog("=== i18n Key Check ===")
+
+	if (!results || results.length === 0) {
+		bufferLog("\n✅ All i18n keys are present!")
+	} else {
+		bufferLog("\n❌ Missing i18n keys:")
+
+		// Group by file status
+		const missingFiles = new Set<string>()
+		const missingKeys = new Map<string, Set<string>>()
+
+		results.forEach(({ key, missingLocales }) => {
+			missingLocales.forEach(({ path: locale, isFileMissing }) => {
+				if (isFileMissing) {
+					missingFiles.add(locale)
+				} else {
+					if (!missingKeys.has(locale)) {
+						missingKeys.set(locale, new Set())
+					}
+					missingKeys.get(locale)?.add(key)
+				}
+			})
+		})
+
+		// Show missing files first
+		if (missingFiles.size > 0) {
+			bufferLog("\nMissing translation files:")
+			Array.from(missingFiles)
+				.sort()
+				.forEach((file) => {
+					bufferLog(`  - ${file}`)
+				})
+		}
+
+		// Then show files with missing keys
+		if (missingKeys.size > 0) {
+			bufferLog("\nFiles with missing keys:")
+
+			// Group by file path to collect all keys per file
+			const fileKeys = new Map<string, Map<string, Set<string>>>()
+			results.forEach(({ key, file, missingLocales }) => {
+				missingLocales.forEach(({ path: locale, isFileMissing }) => {
+					if (!isFileMissing) {
+						const [_localeDir, _localeFile] = locale.split("/")
+						const filePath = locale
+						if (!fileKeys.has(filePath)) {
+							fileKeys.set(filePath, new Map())
+						}
+						if (!fileKeys.get(filePath)?.has(file)) {
+							fileKeys.get(filePath)?.set(file, new Set())
+						}
+						fileKeys.get(filePath)?.get(file)?.add(key)
+					}
+				})
+			})
+
+			// Show missing keys grouped by file
+			Array.from(fileKeys.entries())
+				.sort()
+				.forEach(([file, sourceFiles]) => {
+					bufferLog(`  - ${file}:`)
+					Array.from(sourceFiles.entries())
+						.sort()
+						.forEach(([_sourceFile, keys]) => {
+							Array.from(keys)
+								.sort()
+								.forEach((key) => {
+									bufferLog(`      ${key}`)
+								})
+						})
+				})
+		}
+
+		// Add simple command line example
+		if (missingKeys.size > 0) {
+			bufferLog("\nTo add missing translations:")
+			bufferLog(
+				"   node scripts/manage-translations.js <locale_file> 'key' 'translation' [ 'key2' 'translation2' ... ]",
+			)
+		}
+	}
+
+	return { output: printLogs() }
+}
+
+describe("Find Missing i18n Keys", () => {
+	test("findMissingI18nKeys scans for missing translations", () => {
+		const result = findMissingI18nKeys()
+		expect(result.output).toContain("✅ All i18n keys are present!")
+	})
+})