babaofan-translate-cli 1.0.0

package/bin/i18n.js

@@ -0,0 +1,1450 @@
+#!/usr/bin/env node
+
+/**
+ * Cool Unix 国际化翻译脚本
+ * 用于扫描项目中的 i18n 调用，自动生成多语言翻译文件
+ */
+
+import { program } from "commander";
+import chalk from "chalk";
+import path from "path";
+import fs from "fs";
+import { globSync } from "glob";
+import { parse as babelParse } from "@babel/parser";
+import { GoogleGenAI } from "@google/genai";
+import { isEmpty } from "lodash-es";
+import { parse as parseSfc } from "@vue/compiler-sfc";
+import { defaultGoogleApiKey } from "../config.js";
+import { getProjectRoot } from "../utils.js";
+
+// ============================================================================
+// 配置常量
+// ============================================================================
+
+const PROJECT_ROOT = getProjectRoot();
+const DEFAULT_BATCH_SIZE = 20;
+const DEFAULT_GEMINI_MODEL = "gemini-2.5-flash";
+const SOURCE_LOCALE = "zh-cn";
+const DEFAULT_OUTPUT_DIR = "locales";
+const SUPPORTED_EXTENSIONS = new Set([
+	".js",
+	".jsx",
+	".mjs",
+	".cjs",
+	".ts",
+	".tsx",
+	".mts",
+	".cts",
+	".vue",
+	".nvue",
+	".uvue",
+	".uts"
+]);
+const BABEL_PLUGINS = ["typescript", "jsx"];
+const COMMON_SCAN_EXTENSIONS = "js,jsx,mjs,cjs,ts,tsx,mts,cts,vue,nvue,uvue,uts";
+const LOCALE_CONFIG_PATTERNS = [
+	"plugins/locale.{js,ts,mjs,cjs}",
+	"src/plugins/locale.{js,ts,mjs,cjs}",
+	"src/i18n/**/*.{js,ts,mjs,cjs,json}",
+	"i18n/**/*.{js,ts,mjs,cjs,json}",
+	"config/**/*locale*.{js,ts,mjs,cjs,json}",
+	"locales/**/*.{js,ts,mjs,cjs,json}"
+];
+const LANGUAGE_KEYS = ["languages", "locales", "supportedLocales", "availableLocales", "supportedLngs"];
+const LOCALE_OUTPUT_FORMATS = new Set(["auto", "pair-array", "object"]);
+const PREVIEW_LIMIT = 10;
+const DEFAULT_IGNORED_DIRS = [
+	"node_modules",
+	"dist",
+	"build",
+	"coverage",
+	".next",
+	".nuxt",
+	".output",
+	".turbo",
+	".git",
+	DEFAULT_OUTPUT_DIR
+];
+
+const LANGUAGE_NAMES = {
+	"zh-cn": "简体中文",
+	"zh-tw": "繁體中文",
+	en: "English",
+	es: "Español",
+	ja: "日本語",
+	ko: "한국어",
+	fr: "Français",
+	de: "Deutsch",
+	pt: "Português",
+	ru: "Русский",
+	ar: "العربية",
+	th: "ไทย",
+	vi: "Tiếng Việt"
+};
+
+// ============================================================================
+// 终端日志工具
+// ============================================================================
+
+const logger = {
+	title(text) {
+		console.log();
+		console.log(chalk.white.bold(text));
+		console.log(chalk.gray("─".repeat(50)));
+	},
+
+	info(label, value) {
+		console.log(chalk.gray("  ●"), chalk.white(label), chalk.cyan(value));
+	},
+
+	success(text) {
+		console.log(chalk.green("  ✓"), chalk.white(text));
+	},
+
+	warn(text) {
+		console.log(chalk.yellow("  ⚠"), chalk.white(text));
+	},
+
+	error(text) {
+		console.log(chalk.red("  ✗"), chalk.white(text));
+	},
+
+	languages(langs) {
+		const formatted = langs
+			.map((lang) => {
+				const name = LANGUAGE_NAMES[lang] || lang;
+				return chalk.cyan(name) + chalk.gray(` (${lang})`);
+			})
+			.join(chalk.gray(" · "));
+		console.log(chalk.gray("  ●"), chalk.white("语言"), formatted);
+	},
+
+	translating(locale, current, total) {
+		const name = LANGUAGE_NAMES[locale] || locale;
+		const percent = total === 0 ? 100 : Math.round((current / total) * 100);
+		const filled = Math.floor(percent / 5);
+		const bar = chalk.cyan("█".repeat(filled)) + chalk.gray("░".repeat(20 - filled));
+
+		process.stdout.clearLine?.(0);
+		process.stdout.cursorTo?.(0);
+		process.stdout.write(
+			`  ${chalk.cyan("⟳")} ${chalk.white("翻译中")} ${bar} ${chalk.green(percent + "%")} ${chalk.gray("→")} ${chalk.cyan(name)}`
+		);
+	},
+
+	translateDone() {
+		process.stdout.clearLine?.(0);
+		process.stdout.cursorTo?.(0);
+		console.log(`  ${chalk.green("✓")} ${chalk.white("翻译完成")}`);
+	},
+
+	file(filePath) {
+		const relativePath = filePath.replace(PROJECT_ROOT, "").replace(/^[\\/]/, "");
+		console.log(chalk.gray("  +"), chalk.green(relativePath));
+	},
+
+	divider() {
+		console.log(chalk.gray("─".repeat(50)));
+	},
+
+	newline() {
+		console.log();
+	},
+
+	progress(label, current, total, size) {
+		console.log(
+			chalk.gray("  ⟳"),
+			chalk.white(label),
+			chalk.cyan(`第 ${current}/${total} 批`),
+			chalk.gray(`(${size} 条)`)
+		);
+	}
+};
+
+// ============================================================================
+// 工具函数
+// ============================================================================
+
+function getProjectLanguages() {
+	return [];
+}
+
+function ensureDirectoryExists(filePath) {
+	const dirPath = path.dirname(filePath);
+	if (!fs.existsSync(dirPath)) {
+		fs.mkdirSync(dirPath, { recursive: true });
+	}
+}
+
+function normalizeContentText(text) {
+	return String(text || "").replace(/^page\./, "");
+}
+
+function hashString(text) {
+	let hash = 2166136261;
+
+	for (let i = 0; i < text.length; i++) {
+		hash ^= text.charCodeAt(i);
+		hash = Math.imul(hash, 16777619);
+	}
+
+	return (hash >>> 0).toString(36);
+}
+
+function normalizeKeySegment(value) {
+	return String(value || "")
+		.toLowerCase()
+		.replace(/\.[^.]+$/, "")
+		.replace(/[^a-z0-9-]+/g, "-")
+		.replace(/^-+|-+$/g, "")
+		.replace(/-{2,}/g, "-");
+}
+
+function buildKeyNamespace(filePath) {
+	const relativePath = path.relative(PROJECT_ROOT, filePath).replace(/\\/g, "/");
+	const rawSegments = relativePath.split("/").filter(Boolean);
+	const ignoredSegments = new Set([
+		"src",
+		"app",
+		"pages",
+		"page",
+		"components",
+		"component",
+		"views",
+		"view",
+		"locales",
+		"tests",
+		"test",
+		"spec",
+		"__tests__"
+	]);
+	const compressibleSegmentPatterns = [
+		/^tmp(?:-.+)?$/,
+		/^temp(?:-.+)?$/,
+		/^test(?:-.+)?$/,
+		/^spec(?:-.+)?$/,
+		/^playground(?:-.+)?$/,
+		/^sandbox(?:-.+)?$/,
+		/^example(?:s)?(?:-.+)?$/,
+		/^demo(?:-.+)?$/
+	];
+
+	const normalizedSegments = rawSegments
+		.map((segment, index) => {
+			const value = index === rawSegments.length - 1 ? segment.replace(/\.[^.]+$/, "") : segment;
+			return normalizeKeySegment(value);
+		})
+		.filter(Boolean)
+		.filter((segment) => !ignoredSegments.has(segment))
+		.filter((segment, index, segments) => {
+			if (segments.length <= 1) {
+				return true;
+			}
+			return !compressibleSegmentPatterns.some((pattern) => pattern.test(segment));
+		});
+
+	return normalizedSegments.slice(-2).join(".") || "common";
+}
+
+function normalizeGeneratedKey(value, namespace, sourceText, usedKeys) {
+	const normalized = String(value || "")
+		.toLowerCase()
+		.replace(/[^a-z0-9]+/g, ".")
+		.replace(/^\.+|\.+$/g, "")
+		.replace(/\.{2,}/g, ".");
+	const baseKey = normalized
+		? normalized.startsWith(`${namespace}.`) || normalized === namespace
+			? normalized
+			: `${namespace}.${normalized}`
+		: `${namespace}.text`;
+	const textHash = hashString(sourceText).slice(0, 6);
+	let key = baseKey;
+
+	if (usedKeys.has(key) && usedKeys.get(key) !== sourceText) {
+		key = `${baseKey}.${textHash}`;
+	}
+
+	let suffix = 1;
+	while (usedKeys.has(key) && usedKeys.get(key) !== sourceText) {
+		suffix += 1;
+		key = `${baseKey}.${textHash}.${suffix}`;
+	}
+
+	usedKeys.set(key, sourceText);
+	return key;
+}
+
+function parseJsonArrayResponse(responseText) {
+	const cleanedText = String(responseText || "")
+		.replace(/```json/gi, "```")
+		.replace(/```/g, "")
+		.trim();
+
+	const parsed = JSON.parse(cleanedText);
+
+	if (!Array.isArray(parsed)) {
+		throw new Error("模型返回结果不是 JSON 数组");
+	}
+
+	return parsed;
+}
+
+async function generateSemanticKeysWithGemini(client, items, model) {
+	const prompt = [
+		"你是一个专业的 i18n key 命名助手。",
+		"请根据给定的文件命名空间和中文文案，为每一项生成一个英文小写 dot.case key。",
+		"要求：",
+		"1. 只返回 JSON 数组字符串，不要 Markdown，不要解释。",
+		"2. 数组长度必须和输入一致，并保持顺序。",
+		"3. key 必须使用英文语义命名，不能包含中文、空格、连字符或下划线。",
+		"4. key 必须以 namespace 开头。",
+		"5. key 要简洁可读，优先表达 UI 含义，例如 button.title、empty.state.title、form.submit.success。",
+		"6. 不要使用拼音，不要直接音译中文。",
+		`输入内容：${JSON.stringify(items)}`
+	].join("\n");
+
+	const response = await client.models.generateContent({
+		model,
+		contents: prompt
+	});
+
+	const responseText =
+		typeof response.text === "function" ? response.text() : response.text || "";
+	const keys = parseJsonArrayResponse(responseText);
+
+	if (keys.length !== items.length) {
+		throw new Error(`模型返回 key 数量异常，期望 ${items.length} 条，实际 ${keys.length} 条`);
+	}
+
+	return keys.map((key) => String(key ?? ""));
+}
+
+function resolveApiKey(cliApiKey) {
+	return (
+		cliApiKey ||
+		defaultGoogleApiKey ||
+		process.env.GEMINI_API_KEY ||
+		process.env.GOOGLE_AI_STUDIO_API_KEY ||
+		process.env.GOOGLE_API_KEY ||
+		""
+	).trim();
+}
+
+function parseBatchSize(value) {
+	const batchSize = Number.parseInt(value, 10);
+	if (!Number.isInteger(batchSize) || batchSize <= 0) {
+		throw new Error("batch-size 必须是大于 0 的整数");
+	}
+	return batchSize;
+}
+
+function parseFilePatterns(value) {
+	return value
+		.split(",")
+		.map((item) => item.trim())
+		.filter(Boolean);
+}
+
+function parseLanguages(value) {
+	return value
+		.split(",")
+		.map((item) => item.trim())
+		.filter(Boolean);
+}
+
+function parseOutputFormat(value) {
+	const format = String(value || "auto").trim().toLowerCase();
+	if (!LOCALE_OUTPUT_FORMATS.has(format)) {
+		throw new Error(`output-format 仅支持 ${[...LOCALE_OUTPUT_FORMATS].join(" / ")}`);
+	}
+	return format;
+}
+
+function safeReadJsonFile(filePath) {
+	if (!fs.existsSync(filePath)) {
+		return null;
+	}
+
+	try {
+		return JSON.parse(fs.readFileSync(filePath, "utf8"));
+	} catch (error) {
+		logger.warn(`JSON 解析失败，已忽略 ${path.relative(PROJECT_ROOT, filePath)}: ${error.message}`);
+		return null;
+	}
+}
+
+function resolveScanTargets(modulePath, filePatterns = []) {
+	if (!filePatterns.length) {
+		const baseDir = path.join(PROJECT_ROOT, modulePath || "");
+		return [baseDir];
+	}
+
+	return filePatterns.map((pattern) => {
+		if (path.isAbsolute(pattern)) {
+			return pattern;
+		}
+		return path.join(PROJECT_ROOT, pattern);
+	});
+}
+
+function shouldIgnoreFile(filePath, includeUniModules = false) {
+	const relativePath = path.relative(PROJECT_ROOT, filePath).replace(/\\/g, "/");
+	const segments = relativePath.split("/").filter(Boolean);
+
+	if (!includeUniModules && segments.includes("uni_modules")) {
+		return true;
+	}
+
+	return DEFAULT_IGNORED_DIRS.some((dirName) => segments.includes(dirName));
+}
+
+function expandScanFiles(targets, includeUniModules = false) {
+	const files = new Set();
+
+	for (const target of targets) {
+		const resolvedTarget = path.resolve(target);
+
+		if (fs.existsSync(resolvedTarget)) {
+			const stat = fs.statSync(resolvedTarget);
+
+			if (stat.isDirectory()) {
+				const matchedFiles = globSync(
+					`${resolvedTarget.replace(/\\/g, "/")}/**/*.{${COMMON_SCAN_EXTENSIONS}}`,
+					{
+						nodir: true,
+						ignore: DEFAULT_IGNORED_DIRS.map((dirName) => `**/${dirName}/**`)
+					}
+				);
+				matchedFiles.forEach((file) => files.add(path.resolve(file)));
+				continue;
+			}
+
+			if (stat.isFile() && SUPPORTED_EXTENSIONS.has(path.extname(resolvedTarget))) {
+				files.add(resolvedTarget);
+			}
+			continue;
+		}
+
+		const matchedFiles = globSync(target.replace(/\\/g, "/"), {
+			nodir: true,
+			absolute: true,
+			ignore: DEFAULT_IGNORED_DIRS.map((dirName) => `**/${dirName}/**`)
+		});
+
+		for (const file of matchedFiles) {
+			if (SUPPORTED_EXTENSIONS.has(path.extname(file))) {
+				files.add(path.resolve(file));
+			}
+		}
+	}
+
+	return [...files].filter((file) => !shouldIgnoreFile(file, includeUniModules));
+}
+
+function walkAstNode(node, visitor) {
+	if (!node || typeof node !== "object") {
+		return;
+	}
+
+	visitor(node);
+
+	if (Array.isArray(node)) {
+		node.forEach((item) => walkAstNode(item, visitor));
+		return;
+	}
+
+	for (const value of Object.values(node)) {
+		if (!value || typeof value !== "object") {
+			continue;
+		}
+		walkAstNode(value, visitor);
+	}
+}
+
+function getStaticCallArgument(node) {
+	if (!node) {
+		return null;
+	}
+
+	if (node.type === "StringLiteral") {
+		return node.value;
+	}
+
+	if (node.type === "TemplateLiteral" && node.expressions.length === 0) {
+		return node.quasis.map((item) => item.value.cooked || "").join("");
+	}
+
+	return null;
+}
+
+function isTargetI18nCallee(node) {
+	if (!node) {
+		return false;
+	}
+
+	if (node.type === "Identifier") {
+		return node.name === "t" || node.name === "$t";
+	}
+
+	if (
+		node.type === "MemberExpression" &&
+		!node.computed &&
+		node.property?.type === "Identifier" &&
+		(node.property.name === "t" || node.property.name === "$t")
+	) {
+		return true;
+	}
+
+	return false;
+}
+
+function collectI18nKeysFromJavaScriptAst(ast) {
+	const keys = [];
+
+	walkAstNode(ast, (node) => {
+		if (node.type !== "CallExpression" || !isTargetI18nCallee(node.callee)) {
+			return;
+		}
+
+		const key = getStaticCallArgument(node.arguments?.[0]);
+		if (key) {
+			keys.push(key);
+		}
+	});
+
+	return keys;
+}
+
+function collectI18nCallsFromJavaScriptAst(ast, filePath, baseOffset = 0, indexShift = 0) {
+	const calls = [];
+
+	walkAstNode(ast, (node) => {
+		if (node.type !== "CallExpression" || !isTargetI18nCallee(node.callee)) {
+			return;
+		}
+
+		const argumentNode = node.arguments?.[0];
+		const sourceText = getStaticCallArgument(argumentNode);
+
+		if (!sourceText || typeof argumentNode?.start !== "number" || typeof argumentNode?.end !== "number") {
+			return;
+		}
+
+		calls.push({
+			filePath,
+			sourceText,
+			start: baseOffset + argumentNode.start - indexShift,
+			end: baseOffset + argumentNode.end - indexShift
+		});
+	});
+
+	return calls;
+}
+
+function parseJavaScriptSource(source, filePath, sourceType = "module") {
+	return babelParse(source, {
+		sourceType,
+		errorRecovery: true,
+		plugins: BABEL_PLUGINS,
+		sourceFilename: filePath
+	});
+}
+
+function collectI18nKeysFromScriptContent(source, filePath, sourceType = "module") {
+	if (!source?.trim()) {
+		return [];
+	}
+
+	try {
+		const ast = parseJavaScriptSource(source, filePath, sourceType);
+		return collectI18nKeysFromJavaScriptAst(ast);
+	} catch (error) {
+		logger.warn(`AST 解析失败，已跳过 ${path.relative(PROJECT_ROOT, filePath)}: ${error.message}`);
+		return [];
+	}
+}
+
+function collectI18nCallsFromScriptContent(source, filePath, baseOffset = 0, sourceType = "module") {
+	if (!source?.trim()) {
+		return [];
+	}
+
+	try {
+		const ast = parseJavaScriptSource(source, filePath, sourceType);
+		return collectI18nCallsFromJavaScriptAst(ast, filePath, baseOffset);
+	} catch (error) {
+		logger.warn(`AST 解析失败，已跳过 ${path.relative(PROJECT_ROOT, filePath)}: ${error.message}`);
+		return [];
+	}
+}
+
+function parseTemplateExpression(expression, filePath) {
+	try {
+		return {
+			ast: parseJavaScriptSource(`(${expression})`, filePath, "module"),
+			indexShift: 1
+		};
+	} catch {
+		try {
+			return {
+				ast: parseJavaScriptSource(expression, filePath, "module"),
+				indexShift: 0
+			};
+		} catch (error) {
+			logger.warn(`模板表达式解析失败，已跳过 ${path.relative(PROJECT_ROOT, filePath)}: ${error.message}`);
+			return null;
+		}
+	}
+}
+
+function collectI18nKeysFromVueTemplateAst(templateAst, filePath) {
+	const keys = [];
+
+	walkAstNode(templateAst, (node) => {
+		const isInterpolation = node?.type === 5 && typeof node.content?.content === "string";
+		const isDirectiveExpression =
+			node?.type === 7 && typeof node.exp?.content === "string" && node.exp.content.trim();
+
+		if (!isInterpolation && !isDirectiveExpression) {
+			return;
+		}
+
+		const expression = isInterpolation ? node.content.content : node.exp.content;
+		const expressionAst = parseTemplateExpression(expression, filePath);
+
+		if (!expressionAst) {
+			return;
+		}
+
+		keys.push(...collectI18nKeysFromJavaScriptAst(expressionAst));
+	});
+
+	return keys;
+}
+
+function collectI18nCallsFromVueTemplateAst(templateAst, filePath) {
+	const calls = [];
+
+	walkAstNode(templateAst, (node) => {
+		const isInterpolation = node?.type === 5 && typeof node.content?.content === "string";
+		const isDirectiveExpression =
+			node?.type === 7 && typeof node.exp?.content === "string" && node.exp.content.trim();
+
+		if (!isInterpolation && !isDirectiveExpression) {
+			return;
+		}
+
+		const expressionNode = isInterpolation ? node.content : node.exp;
+		const expression = expressionNode.content;
+		const parsedExpression = parseTemplateExpression(expression, filePath);
+
+		if (!parsedExpression) {
+			return;
+		}
+
+		calls.push(
+			...collectI18nCallsFromJavaScriptAst(
+				parsedExpression.ast,
+				filePath,
+				expressionNode.loc.start.offset,
+				parsedExpression.indexShift
+			)
+		);
+	});
+
+	return calls;
+}
+
+function collectI18nKeysFromFile(filePath) {
+	const extension = path.extname(filePath);
+	const source = fs.readFileSync(filePath, "utf8");
+
+	if (extension === ".vue" || extension === ".nvue" || extension === ".uvue") {
+		try {
+			const { descriptor } = parseSfc(source, { filename: filePath });
+			return [
+				...collectI18nKeysFromScriptContent(descriptor.script?.content || "", filePath),
+				...collectI18nKeysFromScriptContent(descriptor.scriptSetup?.content || "", filePath),
+				...collectI18nKeysFromVueTemplateAst(descriptor.template?.ast, filePath)
+			];
+		} catch (error) {
+			logger.warn(`SFC 解析失败，已跳过 ${path.relative(PROJECT_ROOT, filePath)}: ${error.message}`);
+			return [];
+		}
+	}
+
+	return collectI18nKeysFromScriptContent(source, filePath);
+}
+
+function collectI18nCallsFromFile(filePath) {
+	const extension = path.extname(filePath);
+	const source = fs.readFileSync(filePath, "utf8");
+
+	if (extension === ".vue" || extension === ".nvue" || extension === ".uvue") {
+		try {
+			const { descriptor } = parseSfc(source, { filename: filePath });
+			return [
+				...collectI18nCallsFromScriptContent(
+					descriptor.script?.content || "",
+					filePath,
+					descriptor.script?.loc.start.offset || 0
+				),
+				...collectI18nCallsFromScriptContent(
+					descriptor.scriptSetup?.content || "",
+					filePath,
+					descriptor.scriptSetup?.loc.start.offset || 0
+				),
+				...collectI18nCallsFromVueTemplateAst(descriptor.template?.ast, filePath)
+			];
+		} catch (error) {
+			logger.warn(`SFC 解析失败，已跳过 ${path.relative(PROJECT_ROOT, filePath)}: ${error.message}`);
+			return [];
+		}
+	}
+
+	return collectI18nCallsFromScriptContent(source, filePath);
+}
+
+async function buildRewritePlan(calls, options, progressLabel = "语义命名") {
+	const usedKeys = new Map();
+	const textToKey = new Map();
+	const rewritesByFile = new Map();
+	const entries = [];
+	const uniqueCalls = [];
+
+	for (const call of calls) {
+		if (!textToKey.has(call.sourceText)) {
+			uniqueCalls.push(call);
+		}
+	}
+
+	const keyInputs = uniqueCalls.map((call) => ({
+		namespace: buildKeyNamespace(call.filePath),
+		text: normalizeContentText(call.sourceText),
+		filePath: path.relative(PROJECT_ROOT, call.filePath).replace(/\\/g, "/")
+	}));
+	const generatedKeys = [];
+	const totalBatches = Math.ceil(keyInputs.length / options.batchSize);
+
+	for (let i = 0; i < keyInputs.length; i += options.batchSize) {
+		const batchInputs = keyInputs.slice(i, i + options.batchSize);
+		if (!batchInputs.length) {
+			continue;
+		}
+		const batchIndex = Math.floor(i / options.batchSize) + 1;
+		logger.progress(progressLabel, batchIndex, totalBatches, batchInputs.length);
+		let batchKeys;
+		try {
+			batchKeys = await generateSemanticKeysWithGemini(
+				options.client,
+				batchInputs,
+				options.model
+			);
+		} catch (error) {
+			throw new Error(
+				`${progressLabel}失败：第 ${batchIndex}/${totalBatches} 批（${batchInputs.length} 条）执行失败。${error.message || error}`
+			);
+		}
+		generatedKeys.push(...batchKeys);
+	}
+
+	uniqueCalls.forEach((call, index) => {
+		const normalizedText = normalizeContentText(call.sourceText);
+		const namespace = buildKeyNamespace(call.filePath);
+		const key = normalizeGeneratedKey(generatedKeys[index], namespace, normalizedText, usedKeys);
+		textToKey.set(call.sourceText, key);
+		entries.push({
+			key,
+			sourceText: normalizedText
+		});
+	});
+
+	for (const call of calls) {
+		const key = textToKey.get(call.sourceText);
+
+		if (!rewritesByFile.has(call.filePath)) {
+			rewritesByFile.set(call.filePath, []);
+		}
+
+		rewritesByFile.get(call.filePath).push({
+			start: call.start,
+			end: call.end,
+			replacement: JSON.stringify(key)
+		});
+	}
+
+	return {
+		entries,
+		rewritesByFile
+	};
+}
+
+function applySourceRewrites(rewritesByFile) {
+	for (const [filePath, rewrites] of rewritesByFile.entries()) {
+		if (!rewrites.length) {
+			continue;
+		}
+
+		const source = fs.readFileSync(filePath, "utf8");
+		const sortedRewrites = [...rewrites].sort((a, b) => b.start - a.start);
+		let nextSource = source;
+
+		for (const rewrite of sortedRewrites) {
+			nextSource =
+				nextSource.slice(0, rewrite.start) +
+				rewrite.replacement +
+				nextSource.slice(rewrite.end);
+		}
+
+		if (nextSource !== source) {
+			fs.writeFileSync(filePath, nextSource, "utf8");
+			logger.file(filePath);
+		}
+	}
+}
+
+function extractLanguageArrays(content) {
+	const languages = new Set();
+
+	for (const key of LANGUAGE_KEYS) {
+		const pattern = new RegExp(`${key}\\s*[:=]\\s*\\[([\\s\\S]*?)\\]`, "g");
+		let match;
+
+		while ((match = pattern.exec(content)) !== null) {
+			const values = match[1].match(/['"`]([a-z]{2,3}(?:-[a-z0-9]{2,8})?)['"`]/gi) || [];
+			values.forEach((value) => {
+				const normalized = value.replace(/['"`]/g, "").toLowerCase();
+				languages.add(normalized);
+			});
+		}
+	}
+
+	return [...languages];
+}
+
+function detectProjectLanguages() {
+	const found = new Set();
+
+	for (const pattern of LOCALE_CONFIG_PATTERNS) {
+		const files = globSync(path.join(PROJECT_ROOT, pattern).replace(/\\/g, "/"), {
+			nodir: true,
+			absolute: true
+		});
+
+		for (const file of files) {
+			const content = fs.readFileSync(file, "utf8");
+			extractLanguageArrays(content).forEach((language) => found.add(language));
+		}
+	}
+
+	return [...found];
+}
+
+function resolveLanguages(options) {
+	const languages = options.languages.length ? options.languages : detectProjectLanguages();
+
+	if (!languages.length) {
+		logger.newline();
+		logger.error("未检测到项目语言配置，请使用 --languages 手动传入，例如 zh-cn,en,ja");
+		logger.newline();
+		process.exit(1);
+	}
+
+	if (!languages.includes(options.sourceLocale)) {
+		return [options.sourceLocale, ...languages];
+	}
+
+	return languages;
+}
+
+function detectProjectMode(modulePath) {
+	if (modulePath) {
+		return "uni-module";
+	}
+
+	if (fs.existsSync(path.join(PROJECT_ROOT, "plugins", "locale.ts"))) {
+		return "uniapp";
+	}
+
+	return "generic";
+}
+
+function resolveOutputFormat(options, projectMode) {
+	if (options.outputFormat !== "auto") {
+		return options.outputFormat;
+	}
+
+	return projectMode === "uniapp" || projectMode === "uni-module" ? "pair-array" : "object";
+}
+
+function serializeLocaleEntries(translations, langCode, outputFormat, sourceLocale) {
+	if (outputFormat === "pair-array") {
+		return Object.entries(translations).map(([key, value]) => {
+			return [key, value || ""];
+		});
+	}
+
+	return Object.fromEntries(Object.entries(translations).map(([key, value]) => [key, value || ""]));
+}
+
+function parseLocaleFileToObject(filePath) {
+	const data = safeReadJsonFile(filePath);
+
+	if (!data) {
+		return {};
+	}
+
+	if (Array.isArray(data)) {
+		return Object.fromEntries(
+			data.filter((item) => Array.isArray(item) && item.length >= 2).map(([key, value]) => [key, value || ""])
+		);
+	}
+
+	if (typeof data === "object") {
+		return Object.fromEntries(Object.entries(data).map(([key, value]) => [key, value || ""]));
+	}
+
+	return {};
+}
+
+function mergeLocaleTranslations(filePath, translations) {
+	return {
+		...parseLocaleFileToObject(filePath),
+		...translations
+	};
+}
+
+function logDryRunPreview(translationData, options, languages) {
+	const entries = Object.values(translationData.data).flat();
+	const rewriteFiles = [...translationData.rewritesByFile.keys()].map((filePath) =>
+		path.relative(PROJECT_ROOT, filePath).replace(/\\/g, "/")
+	);
+
+	logger.title("预览结果");
+	logger.info("改写文件", String(rewriteFiles.length));
+	logger.info("新增词条", String(entries.length));
+
+	if (rewriteFiles.length) {
+		rewriteFiles.slice(0, PREVIEW_LIMIT).forEach((filePath) => {
+			console.log(chalk.gray("  ·"), chalk.green(filePath));
+		});
+		if (rewriteFiles.length > PREVIEW_LIMIT) {
+			console.log(chalk.gray("  ·"), chalk.white(`还有 ${rewriteFiles.length - PREVIEW_LIMIT} 个文件未展开`));
+		}
+	}
+
+	if (entries.length) {
+		logger.newline();
+		logger.info("Key 预览", `${Math.min(entries.length, PREVIEW_LIMIT)}/${entries.length}`);
+		entries.slice(0, PREVIEW_LIMIT).forEach((entry) => {
+			console.log(chalk.gray("  ·"), chalk.cyan(entry.key), chalk.gray("←"), chalk.white(entry.sourceText));
+		});
+	}
+
+	logger.newline();
+	logger.info("Locale 文件", "");
+	languages.forEach((langCode) => {
+		const filePath = path.join(PROJECT_ROOT, options.outputDir, `${langCode}.json`);
+		const status = fs.existsSync(filePath) ? "合并已有文件" : "新建文件";
+		console.log(
+			chalk.gray("  ·"),
+			chalk.green(path.relative(PROJECT_ROOT, filePath).replace(/\\/g, "/")),
+			chalk.gray(`(${status})`)
+		);
+	});
+
+	logger.newline();
+	logger.warn("dry-run 模式不会翻译或写文件；为预览语义 key，仍可能调用 Google 生成 key");
+	logger.newline();
+}
+
+function createPageCalls(pagesKeys) {
+	return pagesKeys.map((text) => ({
+		filePath: path.join(PROJECT_ROOT, "pages.json"),
+		sourceText: text,
+		start: 0,
+		end: 0
+	}));
+}
+
+// ============================================================================
+// Gemini 翻译
+// ============================================================================
+
+function createGeminiClient(apiKey) {
+	return new GoogleGenAI({ apiKey });
+}
+
+async function translateTextsWithGemini(client, locale, texts, model) {
+	const prompt = [
+		"你是一个专业的 i18n 翻译助手。",
+		`请将 JSON 数组中的简体中文翻译成 ${locale}。`,
+		"行业背景：3D 打印、MJP、SaaS 平台。",
+		"要求：",
+		"1. 只返回 JSON 数组字符串，不要 Markdown，不要解释。",
+		"2. 返回数组长度必须和输入一致，并保持顺序。",
+		"3. 保留占位符、变量名、HTML 标签、换行符、URL、代码片段、大小写和数字。",
+		"4. 遇到品牌名、产品名、模块名时优先保持原文或做最小必要翻译。",
+		`输入内容：${JSON.stringify(texts)}`
+	].join("\n");
+
+	const response = await client.models.generateContent({
+		model,
+		contents: prompt
+	});
+
+	const responseText =
+		typeof response.text === "function" ? response.text() : response.text || "";
+	const translations = parseJsonArrayResponse(responseText);
+
+	if (translations.length !== texts.length) {
+		throw new Error(`模型返回数量异常，期望 ${texts.length} 条，实际 ${translations.length} 条`);
+	}
+
+	return translations.map((text) => String(text ?? ""));
+}
+
+async function translateEntries(locale, entries, options) {
+	const texts = entries.map((entry) => entry.sourceText);
+	const translations = await translateTextsWithGemini(
+		options.client,
+		locale,
+		texts,
+		options.model
+	);
+
+	return entries.reduce((result, entry, index) => {
+		result[entry.key] = translations[index];
+		return result;
+	}, {});
+}
+
+async function translateInBatches(locale, entries, options) {
+	const result = {};
+	const tasks = [];
+
+	for (let i = 0; i < entries.length; i += options.batchSize) {
+		const batchEntries = entries.slice(i, i + options.batchSize);
+		if (!isEmpty(batchEntries)) {
+			tasks.push(
+				translateEntries(locale, batchEntries, options).then((translations) => {
+					Object.assign(result, translations);
+				})
+			);
+		}
+	}
+
+	await Promise.all(tasks);
+	return result;
+}
+
+// ============================================================================
+// 翻译流程处理
+// ============================================================================
+
+async function invokeFlow(params, onProgress) {
+	const result = {
+		app: {},
+		modules: {},
+		plugins: {},
+		uniappx: {},
+		uni_modules: {}
+	};
+
+	const targetLanguages = params.languages.filter((lang) => lang !== params.sourceLocale);
+	const tasks = [];
+	let completed = 0;
+	const totalTasks = Object.keys(params.data).length * targetLanguages.length;
+
+	for (const key in params.data) {
+		const [type, module] = key.split(".");
+		const rawEntries = params.data[key];
+		const entries = rawEntries.map((entry) => {
+			if (entry && typeof entry === "object" && "key" in entry && "sourceText" in entry) {
+				return {
+					key: String(entry.key),
+					sourceText: normalizeContentText(entry.sourceText)
+				};
+			}
+
+			return {
+				key: String(entry),
+				sourceText: normalizeContentText(entry)
+			};
+		});
+
+		if (!result[type][module]) {
+			result[type][module] = { [params.sourceLocale]: {} };
+			entries.forEach((entry) => {
+				result[type][module][params.sourceLocale][entry.key] = entry.sourceText;
+			});
+		}
+
+		for (const locale of targetLanguages) {
+			const task = translateInBatches(locale, entries, params).then((translations) => {
+				result[type][module][locale] = translations;
+				completed++;
+				onProgress?.(locale, completed, totalTasks);
+			});
+			tasks.push(task);
+		}
+	}
+
+	await Promise.all(tasks);
+	return result;
+}
+
+// ============================================================================
+// 文件扫描与解析
+// ============================================================================
+
+function scanI18nCalls(targets, includeUniModules = false) {
+	const files = expandScanFiles(targets, includeUniModules);
+	const i18nKeys = [];
+
+	files.forEach((file) => {
+		i18nKeys.push(...collectI18nKeysFromFile(file));
+	});
+
+	return i18nKeys;
+}
+
+function scanI18nUsages(targets, includeUniModules = false) {
+	const files = expandScanFiles(targets, includeUniModules);
+	const calls = [];
+
+	files.forEach((file) => {
+		calls.push(...collectI18nCallsFromFile(file));
+	});
+
+	return calls;
+}
+
+function extractFromPagesJson() {
+	const pagesPath = path.join(PROJECT_ROOT, "pages.json");
+
+	if (!fs.existsSync(pagesPath)) {
+		return [];
+	}
+
+	const content = fs.readFileSync(pagesPath, "utf8");
+	const keys = [];
+
+	const percentPattern = /%([^%]+)%/g;
+	let match;
+	while ((match = percentPattern.exec(content)) !== null) {
+		keys.push(match[1]);
+	}
+
+	const navTitlePattern = /"navigationBarTitleText":\s*["'`]([^"'`]+)["'`]/g;
+	while ((match = navTitlePattern.exec(content)) !== null) {
+		if (match[1]?.trim()) {
+			keys.push(match[1]);
+		}
+	}
+
+	const textPattern = /"text":\s*["'`]([^"'`]+)["'`]/g;
+	while ((match = textPattern.exec(content)) !== null) {
+		if (match[1]?.trim()) {
+			keys.push(match[1]);
+		}
+	}
+
+	return keys;
+}
+
+function scanTranslationSources(modulePath = null, filePatterns = []) {
+	const scanTargets = resolveScanTargets(modulePath, filePatterns);
+	const i18nCalls = scanI18nUsages(scanTargets, !!modulePath);
+	const pagesKeys = filePatterns.length ? [] : extractFromPagesJson();
+
+	if (modulePath) {
+		const normalizedModulePath = modulePath.replace(/^[/\\]+/, "");
+		const moduleKey = normalizedModulePath.replace(/[\\/]/g, ".");
+		return {
+			moduleKey,
+			i18nCalls,
+			pagesKeys: []
+		};
+	}
+
+	return {
+		moduleKey: "app.default",
+		i18nCalls,
+		pagesKeys
+	};
+}
+
+async function collectTranslationData(scanResult, options) {
+	const rewritePlan = await buildRewritePlan(scanResult.i18nCalls, options, "语义命名");
+	const pageEntries = scanResult.pagesKeys.length
+		? (await buildRewritePlan(createPageCalls(scanResult.pagesKeys), options, "页面词条命名")).entries
+		: [];
+
+	return {
+		data: {
+			[scanResult.moduleKey]: [
+				...rewritePlan.entries,
+				...pageEntries
+			]
+		},
+		rewritesByFile: rewritePlan.rewritesByFile
+	};
+}
+
+// ============================================================================
+// 翻译文件生成
+// ============================================================================
+
+function writeUniModulesLocales(modulesData, options) {
+	for (const moduleName in modulesData) {
+		const moduleTranslations = modulesData[moduleName];
+
+		for (const langCode in moduleTranslations) {
+			const translations = moduleTranslations[langCode];
+			const fileName = langCode.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
+			const filePath = path.join(
+				PROJECT_ROOT,
+				"uni_modules",
+				moduleName,
+				options.outputDir,
+				`${fileName}.json`
+			);
+			const mergedTranslations = mergeLocaleTranslations(filePath, translations);
+			const data = serializeLocaleEntries(
+				mergedTranslations,
+				langCode,
+				options.outputFormat,
+				options.sourceLocale
+			);
+
+			ensureDirectoryExists(filePath);
+			fs.writeFileSync(filePath, JSON.stringify(data, null, 2), "utf8");
+			logger.file(filePath);
+		}
+	}
+}
+
+function writeBusinessLocales(businessData, options) {
+	for (const langCode in businessData) {
+		const translations = businessData[langCode];
+		const fileName = langCode.replace(/([a-z])([A-Z])/g, "$1-$2").toLowerCase();
+		const filePath = path.join(PROJECT_ROOT, options.outputDir, `${fileName}.json`);
+		const mergedTranslations = mergeLocaleTranslations(filePath, translations);
+		const data = serializeLocaleEntries(
+			mergedTranslations,
+			langCode,
+			options.outputFormat,
+			options.sourceLocale
+		);
+		ensureDirectoryExists(filePath);
+		fs.writeFileSync(filePath, JSON.stringify(data, null, 2), "utf8");
+		logger.file(filePath);
+	}
+}
+
+async function generateLocaleFiles(scanResult, options) {
+	const languages = resolveLanguages(options);
+	const pendingCallsCount = scanResult.i18nCalls.length + scanResult.pagesKeys.length;
+
+	logger.title("开始翻译");
+	logger.info("项目", PROJECT_ROOT);
+	logger.info("提供方", "Google AI Studio");
+	logger.info("模型", options.model);
+	logger.info("批次", String(options.batchSize));
+	logger.info("输出目录", options.outputDir);
+	logger.info("输出格式", options.outputFormat);
+	logger.info("源码回写", options.rewrite ? "开启" : "关闭");
+	logger.info("预览模式", options.dryRun ? "开启" : "关闭");
+	if (options.filePatterns.length) {
+		logger.info("扫描范围", options.filePatterns.join(", "));
+	}
+	logger.languages(languages);
+	logger.info("待处理调用", chalk.yellow(pendingCallsCount) + " 个");
+	logger.divider();
+	logger.newline();
+
+	if (pendingCallsCount === 0) {
+		logger.warn("未扫描到任何 $t()/t() 词条");
+		logger.newline();
+		return;
+	}
+
+	logger.info("语义命名", "正在调用 Google AI 生成语义 key...");
+	logger.newline();
+
+	const translationData = await collectTranslationData(scanResult, options);
+
+	for (const key in translationData.data) {
+		const seen = new Set();
+		translationData.data[key] = translationData.data[key].filter((entry) => {
+			if (!entry?.key || seen.has(entry.key)) {
+				return false;
+			}
+			seen.add(entry.key);
+			return true;
+		});
+	}
+
+	const totalKeys = Object.values(translationData.data).flat().length;
+	logger.success(`语义 key 生成完成，共 ${totalKeys} 个`);
+	logger.newline();
+
+	if (options.dryRun) {
+		logDryRunPreview(translationData, options, languages);
+		return;
+	}
+
+	try {
+		const startTime = Date.now();
+
+		const result = await invokeFlow(
+			{
+				languages,
+				data: translationData.data,
+				client: options.client,
+				model: options.model,
+				batchSize: options.batchSize,
+				sourceLocale: options.sourceLocale
+			},
+			(locale, current, total) => {
+				logger.translating(locale, current, total);
+			}
+		);
+
+		logger.translateDone();
+		logger.newline();
+
+		if (options.rewrite) {
+			logger.title("回写源码");
+			applySourceRewrites(translationData.rewritesByFile);
+			logger.newline();
+		}
+
+		logger.title("生成文件");
+
+		if (result.uni_modules && Object.keys(result.uni_modules).length > 0) {
+			writeUniModulesLocales(result.uni_modules, options);
+		}
+
+		if (result.app?.default) {
+			writeBusinessLocales(result.app.default, options);
+		}
+
+		const duration = ((Date.now() - startTime) / 1000).toFixed(1);
+		logger.newline();
+		logger.divider();
+		console.log(chalk.green.bold("✓ 翻译完成"), chalk.gray(`耗时 ${duration}s`));
+		logger.newline();
+	} catch (err) {
+		logger.newline();
+		logger.error(err.message || "翻译失败");
+		process.exit(1);
+	}
+}
+
+// ============================================================================
+// 命令处理
+// ============================================================================
+
+function buildCommandOptions(commandOptions) {
+	const apiKey = resolveApiKey(commandOptions.apiKey);
+
+	if (!apiKey) {
+		logger.newline();
+		logger.error("缺少 Google AI Studio API Key，请在 config.js 中填写默认值，或使用 --apiKey / --api-key");
+		logger.newline();
+		process.exit(1);
+	}
+
+	return {
+		apiKey,
+		model: commandOptions.model || DEFAULT_GEMINI_MODEL,
+		batchSize: parseBatchSize(commandOptions.batchSize || String(DEFAULT_BATCH_SIZE)),
+		filePatterns: commandOptions.files ? parseFilePatterns(commandOptions.files) : [],
+		languages: commandOptions.languages ? parseLanguages(commandOptions.languages) : [],
+		outputDir: commandOptions.outputDir || DEFAULT_OUTPUT_DIR,
+		outputFormat: parseOutputFormat(commandOptions.outputFormat || "auto"),
+		sourceLocale: (commandOptions.sourceLocale || SOURCE_LOCALE).toLowerCase(),
+		rewrite: commandOptions.rewrite !== false,
+		dryRun: Boolean(commandOptions.dryRun)
+	};
+}
+
+async function createCommand(modulePath = null, commandOptions = {}) {
+	const options = buildCommandOptions(commandOptions);
+	options.client = createGeminiClient(options.apiKey);
+	const projectMode = detectProjectMode(modulePath);
+	options.outputFormat = resolveOutputFormat(options, projectMode);
+	if (projectMode === "uni-module" && options.outputDir === DEFAULT_OUTPUT_DIR) {
+		options.outputDir = "locales";
+	}
+	const scanResult = scanTranslationSources(modulePath, options.filePatterns);
+	await generateLocaleFiles(scanResult, options);
+}
+
+async function addCommand(moduleName, commandOptions) {
+	if (!moduleName?.startsWith("uni_modules/")) {
+		logger.newline();
+		logger.error("格式错误，请输入 uni_modules/[name]");
+		logger.newline();
+		process.exit(1);
+	}
+
+	await createCommand(`/${moduleName}`, commandOptions);
+}
+
+function clearCommand() {
+	logger.title("清除翻译文件");
+
+	const localesDir = path.join(PROJECT_ROOT, DEFAULT_OUTPUT_DIR);
+
+	if (fs.existsSync(localesDir)) {
+		fs.rmSync(localesDir, { recursive: true, force: true });
+		logger.file(localesDir);
+	} else {
+		logger.warn("未找到 locales 目录，无需清理");
+	}
+
+	logger.newline();
+	logger.success("清除完成");
+	logger.newline();
+}
+
+function applySharedOptions(command) {
+	return command
+		.option("-k, --api-key <key>", "Google AI Studio API Key")
+		.option("--apiKey <key>", "Google AI Studio API Key，兼容 npm run xxx -- --apiKey=***")
+		.option("-m, --model <model>", "Gemini 模型名称", DEFAULT_GEMINI_MODEL)
+		.option("-b, --batch-size <size>", "单批翻译数量", String(DEFAULT_BATCH_SIZE))
+		.option("-f, --files <paths>", "只扫描指定文件或 glob，多个值用英文逗号分隔")
+		.option("-l, --languages <codes>", "目标语言列表，多个值用英文逗号分隔，例如 zh-cn,en,ja")
+		.option("-o, --output-dir <dir>", "翻译文件输出目录", DEFAULT_OUTPUT_DIR)
+		.option("--output-format <format>", "输出格式：auto | pair-array | object", "auto")
+		.option("--source-locale <code>", "源语言代码", SOURCE_LOCALE)
+		.option("--no-rewrite", "只生成 locale 文件，不改写源码")
+		.option("--dry-run", "预览将要生成的 key、改写文件和 locale 输出，不真正写入");
+}
+
+// ============================================================================
+// CLI 命令注册
+// ============================================================================
+
+program
+	.name("babaofan-translate")
+	.description(chalk.cyan("本地 i18n 翻译与语义 key 生成工具"))
+	.version("1.0.0");
+
+applySharedOptions(program.command("create").description("创建项目翻译文件")).action(async (options) => {
+	await createCommand(null, options);
+});
+
+program.command("clear").description("清除翻译文件").action(clearCommand);
+
+applySharedOptions(
+	program.command("add <uni_modules/[name]>").description("为指定模块生成翻译文件")
+).action(async (moduleName, options) => {
+	await addCommand(moduleName, options);
+});
+
+program.parseAsync(process.argv);