@chaoswise/intl 3.0.0 → 3.1.0

package/bin/scripts/util/findZhCnInFile.js

@@ -0,0 +1,377 @@
+/**
+ * findZhCnInFile.js
+ *
+ * Scans a single source file for Chinese characters across all node types:
+ *   - comment    : inline / block comments
+ *   - string     : string literals
+ *   - template   : template literal quasis
+ *   - jsx        : JSX text content (outside ignored components)
+ *   - jsx-svg    : JSX text content INSIDE an ignored component (e.g. <svg>)
+ *                  NOT auto-fixable via intl.get() — needs manual SVG handling
+ *   - identifier : identifier names (rare, manual fix needed)
+ *
+ * Returns an array of Finding objects:
+ *   { filePath, type, line, col, content, start?, end? }
+ */
+
+const fs = require('fs');
+const babel = require('@babel/core');
+const traverse = require('@babel/traverse').default;
+const buildTransformOptions = require('./babelOptions');
+// Note: recast is intentionally NOT imported here. findZhCnInFile is a read-only
+// scanner: it only needs babel.parseSync + @babel/traverse, which give accurate
+// char-index positions for the original source.  Importing recast would cause
+// it to expand \t to spaces before parsing, shifting all token positions after
+// any tab character and corrupting the start/end offsets used by fixZhCnInFile.
+
+// Default Chinese character range (same as primaryRegx default)
+const DEFAULT_ZH_REGEX = /[\u4e00-\u9fa5]/;
+
+/**
+ * Parse nozhcn-disable / nozhcn-enable block comments and
+ * nozhcn-disable-line single-line disable directives.
+ * Returns a Set of line numbers that should be skipped.
+ */
+function getNoZhCnIgnoreLines(ast) {
+  const ignoreBlocks = [];
+
+  function processComment(comment) {
+    const { type, value, loc } = comment;
+    const last = ignoreBlocks.length - 1;
+
+    if (type === 'CommentLine' && value.trim() === 'nozhcn-disable-line') {
+      ignoreBlocks.push({ start: loc.start.line, end: loc.start.line });
+      return;
+    }
+    if (type === 'CommentBlock' && value.trim() === 'nozhcn-disable') {
+      if (last < 0 || ignoreBlocks[last].end !== undefined) {
+        ignoreBlocks.push({ start: loc.start.line });
+      }
+      return;
+    }
+    if (type === 'CommentBlock' && value.trim() === 'nozhcn-enable') {
+      if (last >= 0 && ignoreBlocks[last].end === undefined) {
+        ignoreBlocks[last].end = loc.start.line;
+      }
+    }
+  }
+
+  if (ast.comments && Array.isArray(ast.comments)) {
+    ast.comments.forEach(processComment);
+  }
+  if (ast.tokens && Array.isArray(ast.tokens)) {
+    ast.tokens.forEach((token) => {
+      if (token.type === 'CommentLine' || token.type === 'CommentBlock') {
+        processComment(token);
+      }
+    });
+  }
+
+  // Unclosed disable block extends to end of file
+  const len = ignoreBlocks.length;
+  if (len > 0 && ignoreBlocks[len - 1].end === undefined && ast.loc && ast.loc.end) {
+    ignoreBlocks[len - 1].end = ast.loc.end.line;
+  }
+
+  const ignoreLines = new Set();
+  for (const block of ignoreBlocks) {
+    for (let i = block.start; i <= (block.end || block.start); i++) {
+      ignoreLines.add(i);
+    }
+  }
+  return ignoreLines;
+}
+
+/**
+ * Check whether a StringLiteral/TemplateLiteral is an i18n .d() default value.
+ * Pattern: intl.get('key').d('中文')   or   i18nMethod('key').d('中文')
+ *
+ * @param {NodePath} nodePath  - the babel NodePath of the literal node
+ * @param {string}   i18nMethod            - e.g. 'get'
+ * @param {string}   i18nDefaultFunctionKey - e.g. 'd'
+ * @param {string}   i18nObject            - e.g. 'intl'
+ */
+function isI18nDefaultValue(nodePath, i18nMethod, i18nDefaultFunctionKey, i18nObject) {
+  const parent = nodePath.parent;
+  if (!parent || parent.type !== 'CallExpression') return false;
+
+  const callee = parent.callee;
+  if (!callee || callee.type !== 'MemberExpression') return false;
+  if (callee.property.name !== i18nDefaultFunctionKey) return false;
+
+  // callee.object should be a call to i18nObject.i18nMethod(...)
+  const innerCall = callee.object;
+  if (!innerCall || innerCall.type !== 'CallExpression') return false;
+
+  const innerCallee = innerCall.callee;
+  if (!innerCallee) return false;
+
+  if (innerCallee.type === 'MemberExpression') {
+    // intl.get(...)
+    return (
+      innerCallee.property.name === i18nMethod &&
+      (!i18nObject || innerCallee.object.name === i18nObject)
+    );
+  }
+  if (innerCallee.type === 'Identifier') {
+    // get(...) without i18nObject prefix
+    return innerCallee.name === i18nMethod && !i18nObject;
+  }
+  return false;
+}
+
+/**
+ * Collect all comment tokens from the AST.
+ * We use ast.tokens (with parserOpts.tokens:true) as the primary source
+ * because it carries reliable start/end byte offsets needed for fixing.
+ * We deduplicate using start position.
+ */
+function collectCommentTokens(ast) {
+  const seen = new Set();
+  const comments = [];
+
+  function add(c) {
+    if (seen.has(c.start)) return;
+    seen.add(c.start);
+    comments.push(c);
+  }
+
+  // From ast.comments (Babel Program node)
+  if (ast.comments && Array.isArray(ast.comments)) {
+    ast.comments.forEach(add);
+  }
+  // From ast.tokens (recast / Babel with tokens:true)
+  if (ast.tokens && Array.isArray(ast.tokens)) {
+    ast.tokens.forEach((token) => {
+      if (token.type === 'CommentLine' || token.type === 'CommentBlock') {
+        add(token);
+      }
+    });
+  }
+
+  return comments;
+}
+
+/**
+ * Main export: scan a single file and return all Chinese findings.
+ *
+ * @param {string} filePath  - absolute path to the file
+ * @param {object} opts
+ *   - checkTypes          string[]  - which types to scan
+ *   - babelPresets        array
+ *   - babelPlugins        array
+ *   - primaryRegx         RegExp    - Chinese detection regex
+ *   - i18nObject          string
+ *   - i18nMethod          string
+ *   - i18nDefaultFunctionKey string
+ *   - ignoreI18nDefault   boolean   - skip .d('中文') default values
+ *   - ignoreComponents    string[]  - JSX component names whose content is
+ *                                    tagged as 'jsx-svg' instead of 'jsx'
+ *                                    (e.g. ['svg', 'style'])
+ *
+ * @returns {{ findings: Finding[], error: string|null }}
+ */
+module.exports = function findZhCnInFile(filePath, opts) {
+  const {
+    checkTypes = ['comment', 'string', 'template', 'jsx'],
+    babelPresets = [],
+    babelPlugins = [],
+    primaryRegx = DEFAULT_ZH_REGEX,
+    i18nObject = 'intl',
+    i18nMethod = 'get',
+    i18nDefaultFunctionKey = 'd',
+    ignoreI18nDefault = true,
+    ignoreComponents = ['svg', 'style'],
+  } = opts || {};
+
+  const findings = [];
+
+  // ── Read source ──────────────────────────────────────────────────────
+  let source;
+  try {
+    source = fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    return { findings, error: `Cannot read file: ${err.message}` };
+  }
+
+  // Fast-path: skip files with no Chinese at all
+  if (!primaryRegx.test(source)) {
+    return { findings, error: null };
+  }
+
+  // ── Parse AST ────────────────────────────────────────────────────────
+  // Parse with babel.parseSync directly on the original source string.
+  // We intentionally do NOT go through recast here: recast expands \t to spaces
+  // before passing the source to the parser, which shifts all token start/end
+  // positions after each tab by (tabWidth - 1) characters.  Those shifted
+  // positions would then be wrong when used by fixZhCnInFile to patch the
+  // original (non-expanded) file on disk.
+  const transformOptions = buildTransformOptions(babelPresets, babelPlugins);
+  let ast;
+  try {
+    ast = babel.parseSync(source, transformOptions);
+  } catch (err) {
+    return { findings, error: `Parse error: ${err.message}` };
+  }
+
+  const ignoreLines = getNoZhCnIgnoreLines(ast);
+
+  function isIgnoredLine(line) {
+    return ignoreLines.has(line);
+  }
+
+  // ── Scan comments ────────────────────────────────────────────────────
+  if (checkTypes.includes('comment')) {
+    const commentTokens = collectCommentTokens(ast);
+    commentTokens.forEach((comment) => {
+      const line = comment.loc && comment.loc.start.line;
+
+      // Skip nozhcn control directives themselves
+      const trimmedValue = comment.value.trim();
+      if (
+        trimmedValue === 'nozhcn-disable-line' ||
+        trimmedValue === 'nozhcn-disable' ||
+        trimmedValue === 'nozhcn-enable' ||
+        trimmedValue === 'cw-i18n-disable-line' ||
+        trimmedValue === 'cw-i18n-disable' ||
+        trimmedValue === 'cw-i18n-enable'
+      ) {
+        return;
+      }
+
+      if (isIgnoredLine(line)) return;
+      if (!primaryRegx.test(comment.value)) return;
+
+      const delimiter =
+        comment.type === 'CommentLine' ? `//${comment.value}` : `/*${comment.value}*/`;
+
+      findings.push({
+        filePath,
+        type: 'comment',
+        line,
+        col: comment.loc ? comment.loc.start.column : 0,
+        content: delimiter,
+        commentType: comment.type,
+        // Byte offsets for fixZhCnInFile
+        start: comment.start,
+        end: comment.end,
+      });
+    });
+  }
+
+  // ── Traverse AST nodes ───────────────────────────────────────────────
+  const needsAstScan =
+    checkTypes.includes('string') ||
+    checkTypes.includes('template') ||
+    checkTypes.includes('jsx') ||
+    checkTypes.includes('jsx-svg') ||
+    checkTypes.includes('identifier');
+
+  if (needsAstScan) {
+    traverse(ast, {
+      // ── String literals ─────────────────────────────────────────────
+      StringLiteral(nodePath) {
+        if (!checkTypes.includes('string')) return;
+        const node = nodePath.node;
+        if (!primaryRegx.test(node.value)) return;
+        if (isIgnoredLine(node.loc && node.loc.start.line)) return;
+        if (
+          ignoreI18nDefault &&
+          isI18nDefaultValue(nodePath, i18nMethod, i18nDefaultFunctionKey, i18nObject)
+        ) {
+          return;
+        }
+        findings.push({
+          filePath,
+          type: 'string',
+          line: node.loc && node.loc.start.line,
+          col: node.loc && node.loc.start.column,
+          content: node.value,
+        });
+      },
+
+      // ── Template literal quasis ─────────────────────────────────────
+      TemplateLiteral(nodePath) {
+        if (!checkTypes.includes('template')) return;
+        // Skip `intl.get('key').d(\`中文\`)` default values when ignoreI18nDefault is on
+        if (
+          ignoreI18nDefault &&
+          isI18nDefaultValue(nodePath, i18nMethod, i18nDefaultFunctionKey, i18nObject)
+        ) {
+          return;
+        }
+        nodePath.node.quasis.forEach((quasi) => {
+          if (!primaryRegx.test(quasi.value.raw)) return;
+          if (isIgnoredLine(quasi.loc && quasi.loc.start.line)) return;
+          findings.push({
+            filePath,
+            type: 'template',
+            line: quasi.loc && quasi.loc.start.line,
+            col: quasi.loc && quasi.loc.start.column,
+            content: quasi.value.raw,
+          });
+        });
+      },
+
+      // ── JSX text ────────────────────────────────────────────────────
+      JSXText(nodePath) {
+        if (!checkTypes.includes('jsx') && !checkTypes.includes('jsx-svg')) return;
+        const node = nodePath.node;
+        const text = node.value.trim();
+        if (!text || !primaryRegx.test(text)) return;
+        if (isIgnoredLine(node.loc && node.loc.start.line)) return;
+
+        // Walk up the ancestor chain to see if we are inside an ignored
+        // component (e.g. <svg>, <style>).  If so, tag as 'jsx-svg' so
+        // the caller knows this cannot be fixed via intl.get().
+        let insideIgnored = false;
+        nodePath.findParent((p) => {
+          if (!p.isJSXElement()) return false;
+          const openingName = p.node.openingElement && p.node.openingElement.name;
+          if (!openingName) return false;
+          // Handle plain tags (name.name) and namespaced tags (name.namespace.name)
+          const componentName =
+            openingName.name ||
+            (openingName.namespace && openingName.namespace.name) ||
+            '';
+          if (ignoreComponents.includes(componentName)) {
+            insideIgnored = true;
+            return true; // stop traversal
+          }
+          return false;
+        });
+
+        const type = insideIgnored ? 'jsx-svg' : 'jsx';
+        if (!checkTypes.includes(type)) return;
+
+        findings.push({
+          filePath,
+          type,
+          line: node.loc && node.loc.start.line,
+          col: node.loc && node.loc.start.column,
+          content: text,
+        });
+      },
+
+      // ── Identifiers (variable / function / class names) ─────────────
+      Identifier(nodePath) {
+        if (!checkTypes.includes('identifier')) return;
+        const node = nodePath.node;
+        if (!primaryRegx.test(node.name)) return;
+        if (isIgnoredLine(node.loc && node.loc.start.line)) return;
+        findings.push({
+          filePath,
+          type: 'identifier',
+          line: node.loc && node.loc.start.line,
+          col: node.loc && node.loc.start.column,
+          content: node.name,
+        });
+      },
+    });
+  }
+
+  // Sort findings by line number for consistent output
+  findings.sort((a, b) => (a.line || 0) - (b.line || 0));
+
+  return { findings, error: null };
+};

package/bin/scripts/util/findZhCnInSvgFile.js

@@ -0,0 +1,139 @@
+/**
+ * findZhCnInSvgFile.js
+ *
+ * Scans a standalone SVG (XML) file for Chinese characters.
+ * Uses regex-based parsing rather than a full XML AST to keep the
+ * dependency footprint minimal.
+ *
+ * SVG finding types
+ * ─────────────────
+ *   svg-comment   : <!-- 中文注释 -->
+ *   svg-metadata  : content inside <title>, <desc>, <metadata> elements
+ *                   (usually design-tool exports; safe to auto-fix)
+ *   svg-text      : content inside <text> elements (visible output)
+ *                   (NOT auto-fixable — requires design decision)
+ *   svg-attr      : attribute value containing Chinese
+ *                   (NOT auto-fixable — requires semantic decision)
+ *
+ * Ignore directive
+ * ────────────────
+ *   Any line containing `nozhcn-disable-line` anywhere in it is skipped.
+ *   Block ignore is not supported in SVG (XML comments only).
+ */
+
+const fs = require('fs');
+
+const ZH_REGEX = /[\u4e00-\u9fa5]/;
+const ZH_REGEX_GLOBAL = /[\u4e00-\u9fa5]/g;
+
+/**
+ * Compute the 1-based line number for a given byte offset in `source`.
+ */
+function lineOf(source, index) {
+  let line = 1;
+  for (let i = 0; i < index; i++) {
+    if (source[i] === '\n') line++;
+  }
+  return line;
+}
+
+/**
+ * Compute the 0-based column for a given byte offset in `source`.
+ */
+function colOf(source, index) {
+  let col = 0;
+  for (let i = index - 1; i >= 0 && source[i] !== '\n'; i--) {
+    col++;
+  }
+  return col;
+}
+
+/**
+ * Get the set of line numbers that contain a `nozhcn-disable-line` directive in
+ * SVG: we look for the directive in XML comments on the same line.
+ */
+function getIgnoredLines(source) {
+  const ignored = new Set();
+  const lines = source.split('\n');
+  lines.forEach((line, idx) => {
+    if (/nozhcn-disable-line/.test(line)) {
+      ignored.add(idx + 1);
+    }
+  });
+  return ignored;
+}
+
+/**
+ * Scan a standalone SVG file for Chinese characters.
+ *
+ * @param {string} filePath  - absolute path to the .svg file
+ * @returns {{ findings: Finding[], error: string|null }}
+ */
+module.exports = function findZhCnInSvgFile(filePath) {
+  let source;
+  try {
+    source = fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    return { findings: [], error: `Cannot read file: ${err.message}` };
+  }
+
+  // Fast-path: skip files with no Chinese at all
+  if (!ZH_REGEX.test(source)) {
+    return { findings: [], error: null };
+  }
+
+  const findings = [];
+  const ignoredLines = getIgnoredLines(source);
+
+  /**
+   * Add a finding only if it contains Chinese and its line is not ignored.
+   * `matchIndex` is the byte offset of the START of the full regex match.
+   * We point the line/col at the FIRST Chinese character in the match.
+   */
+  function addFinding(type, matchStr, matchIndex) {
+    if (!ZH_REGEX.test(matchStr)) return;
+    // Find the offset of the first Chinese char inside this match
+    const zhOffset = matchStr.search(ZH_REGEX);
+    const zhAbsIndex = matchIndex + zhOffset;
+    const line = lineOf(source, zhAbsIndex);
+    if (ignoredLines.has(line)) return;
+    const col = colOf(source, zhAbsIndex);
+    const content = matchStr.replace(/\s+/g, ' ').trim().slice(0, 100);
+    findings.push({ filePath, type, line, col, content });
+  }
+
+  // ── 1. XML comments  <!--...-->  ─────────────────────────────────────────
+  const commentReg = /<!--([\s\S]*?)-->/g;
+  let m;
+  while ((m = commentReg.exec(source)) !== null) {
+    addFinding('svg-comment', m[0], m.index);
+  }
+
+  // ── 2. Metadata elements  <title>, <desc>, <metadata>  ───────────────────
+  // These are typically generated by design tools (Figma, Sketch, Illustrator)
+  // and are safe to remove or empty.
+  const metaReg = /<(title|desc|metadata)(\s[^>]*)?>[\s\S]*?<\/\1>/gi;
+  while ((m = metaReg.exec(source)) !== null) {
+    addFinding('svg-metadata', m[0], m.index);
+  }
+
+  // ── 3. <text> elements (visible rendered text in SVG)  ───────────────────
+  // Can be nested: <text><tspan>中文</tspan></text>
+  // NOT auto-fixable.
+  const textReg = /<text[\s>][\s\S]*?<\/text>/gi;
+  while ((m = textReg.exec(source)) !== null) {
+    addFinding('svg-text', m[0], m.index);
+  }
+
+  // ── 4. Attribute values containing Chinese  ───────────────────────────────
+  // Matches: attr="中文"  or  attr='中文'
+  // NOT auto-fixable.
+  const attrReg = /\s[\w:_-]+=["']([^"']*[\u4e00-\u9fa5][^"']*)["']/g;
+  while ((m = attrReg.exec(source)) !== null) {
+    addFinding('svg-attr', m[0].trim(), m.index);
+  }
+
+  findings.sort((a, b) => a.line - b.line);
+
+  return { findings, error: null };
+};

package/bin/scripts/util/fixI18nDefaultInFile.js

@@ -0,0 +1,179 @@
+/**
+ * fixI18nDefaultInFile.js
+ *
+ * Replaces Chinese text inside .d() default value calls with a translation
+ * loaded from the project's locale JSON file.
+ *
+ * Target pattern (AST):
+ *   intl.get('some-uuid-key').d('中文回退值')
+ *        └── i18nObject.i18nMethod(key).i18nDefaultFunctionKey(chineseText)
+ *
+ * How it works:
+ *   1. Read the locale JSON for `targetLang`
+ *      from `{localeOutput}/locales/{targetLang}.json`
+ *   2. Parse the file with Babel + recast (preserving original formatting)
+ *   3. Traverse AST: find CallExpression nodes matching the .d() pattern
+ *   4. For each match, extract the i18n key from the inner .get() call,
+ *      look up the translation in the locale map
+ *   5. If a translation exists: replace the StringLiteral argument of .d()
+ *      using recast (only the changed node is reprinted)
+ *   6. Write back to file
+ *
+ * Returns { fixed: number, missing: Array<{filePath, key, chinese}> }
+ *   fixed   - number of .d() values successfully replaced
+ *   missing - keys where no translation was found in the locale file
+ */
+
+const fs = require('fs');
+const recast = require('recast');
+const babel = require('@babel/core');
+const traverse = require('@babel/traverse').default;
+const t = require('@babel/types');
+const buildTransformOptions = require('./babelOptions');
+const log = require('./log');
+
+// Chinese character detection regex
+const ZH_REGEX = /[\u4e00-\u9fa5]/;
+
+/**
+ * Extract the i18n key from the "inner" `.get('key')` call that wraps a `.d()`.
+ *
+ * Given the CallExpression node of `.d('中文')`:
+ *   node.callee = MemberExpression { object: CallExpression(.get('key')), property: 'd' }
+ *
+ * @param {ASTNode}  callNode               - the outer CallExpression (.d(...))
+ * @param {string}   i18nMethod             - e.g. 'get'
+ * @param {string}   i18nDefaultFunctionKey - e.g. 'd'
+ * @param {string}   i18nObject             - e.g. 'intl' (may be empty)
+ * @returns {string|null}  the key string, or null if not matched
+ */
+function extractI18nKey(callNode, i18nMethod, i18nDefaultFunctionKey, i18nObject) {
+  const callee = callNode.callee;
+  if (!callee || callee.type !== 'MemberExpression') return null;
+  if (callee.property.name !== i18nDefaultFunctionKey) return null;
+
+  const innerCall = callee.object;
+  if (!innerCall || innerCall.type !== 'CallExpression') return null;
+
+  const innerCallee = innerCall.callee;
+  if (!innerCallee) return null;
+
+  const methodMatches =
+    (innerCallee.type === 'MemberExpression' &&
+      innerCallee.property.name === i18nMethod &&
+      (!i18nObject || innerCallee.object.name === i18nObject)) ||
+    (innerCallee.type === 'Identifier' &&
+      innerCallee.name === i18nMethod &&
+      !i18nObject);
+
+  if (!methodMatches) return null;
+
+  // The first argument of the inner call must be a string literal (the key)
+  const keyArg = innerCall.arguments && innerCall.arguments[0];
+  if (!keyArg || keyArg.type !== 'StringLiteral') return null;
+
+  return keyArg.value;
+}
+
+/**
+ * Fix .d('中文') calls in a single file by replacing Chinese default values
+ * with translations from the locale map.
+ *
+ * @param {string} filePath       - absolute file path
+ * @param {Object} localeMap      - { key: translationText }
+ * @param {Object} opts
+ *   - i18nObject              string  e.g. 'intl'
+ *   - i18nMethod              string  e.g. 'get'
+ *   - i18nDefaultFunctionKey  string  e.g. 'd'
+ *   - babelPresets            array
+ *   - babelPlugins            array
+ *
+ * @returns {{ fixed: number, missing: Array<{key, chinese}> }}
+ */
+module.exports = function fixI18nDefaultInFile(filePath, localeMap, opts) {
+  const {
+    i18nObject = 'intl',
+    i18nMethod = 'get',
+    i18nDefaultFunctionKey = 'd',
+    babelPresets = [],
+    babelPlugins = [],
+  } = opts || {};
+
+  let fixed = 0;
+  const missing = [];
+
+  // ── Read source ──────────────────────────────────────────────────────
+  let source;
+  try {
+    source = fs.readFileSync(filePath, 'utf8');
+  } catch (err) {
+    log.error(`[nozhcn] Cannot read file: ${filePath} — ${err.message}`);
+    return { fixed, missing };
+  }
+
+  // Fast-path: skip files with no Chinese and no i18nMethod calls at all
+  if (!ZH_REGEX.test(source)) {
+    return { fixed, missing };
+  }
+
+  // ── Parse AST ────────────────────────────────────────────────────────
+  const transformOptions = buildTransformOptions(babelPresets, babelPlugins);
+  let recastAst;
+  try {
+    recastAst = recast.parse(source, {
+      parser: {
+        parse(src) {
+          return babel.parseSync(src, transformOptions);
+        },
+      },
+    });
+  } catch (err) {
+    log.error(`[nozhcn] Parse error in ${filePath}: ${err.message}`);
+    return { fixed, missing };
+  }
+
+  // ── Traverse and patch ───────────────────────────────────────────────
+  traverse(recastAst, {
+    CallExpression(nodePath) {
+      const node = nodePath.node;
+
+      // Only process nodes whose single argument is a Chinese StringLiteral
+      const arg = node.arguments && node.arguments[0];
+      if (!arg || arg.type !== 'StringLiteral') return;
+      if (!ZH_REGEX.test(arg.value)) return;
+
+      const key = extractI18nKey(node, i18nMethod, i18nDefaultFunctionKey, i18nObject);
+      if (!key) return;
+
+      const translation = localeMap[key];
+
+      if (!translation) {
+        missing.push({ key, chinese: arg.value });
+        return;
+      }
+
+      // Replace the argument node with a new StringLiteral containing
+      // the translation. We use Object.assign to preserve recast's
+      // original node metadata while updating the value fields.
+      // Setting `extra` to undefined forces recast to re-print using
+      // the new value rather than the cached raw source.
+      Object.assign(arg, t.stringLiteral(translation), { extra: undefined });
+      fixed++;
+    },
+  });
+
+  if (fixed === 0) {
+    return { fixed, missing };
+  }
+
+  // ── Write back using recast (minimal diff) ───────────────────────────
+  const newCode = recast.print(recastAst).code;
+  try {
+    fs.writeFileSync(filePath, newCode, { encoding: 'utf-8' });
+  } catch (err) {
+    log.error(`[nozhcn] Cannot write file: ${filePath} — ${err.message}`);
+    return { fixed: 0, missing };
+  }
+
+  return { fixed, missing };
+};