bctranslate 1.0.1 → 1.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bctranslate",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "CLI to transform source files into i18n-ready code with automatic translation via argostranslate",
   "type": "module",
   "bin": {

package/src/generators/locales.js

@@ -1,5 +1,5 @@
 import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
-import { join, dirname } from 'path';
+import { join } from 'path';
 
 /**
  * Determine the locale directory path based on project type.
@@ -8,6 +8,7 @@ export function getLocaleDir(cwd, project) {
   const candidates = [
     join(cwd, 'src', 'locales'),
     join(cwd, 'src', 'i18n', 'locales'),
+    join(cwd, 'src', 'i18n'),
     join(cwd, 'locales'),
     join(cwd, 'src', 'lang'),
     join(cwd, 'public', 'locales'),
@@ -25,13 +26,53 @@ export function getLocaleDir(cwd, project) {
 }
 
 /**
- * Load an existing locale file, or return empty object.
+ * Flatten a nested JSON object to dot-notation keys.
+ * { home: { notes: 'Notes' } } → { 'home.notes': 'Notes' }
+ */
+function flattenKeys(obj, prefix = '') {
+  const result = {};
+  for (const [key, value] of Object.entries(obj)) {
+    const fullKey = prefix ? `${prefix}.${key}` : key;
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+      Object.assign(result, flattenKeys(value, fullKey));
+    } else {
+      result[fullKey] = value;
+    }
+  }
+  return result;
+}
+
+/**
+ * Unflatten dot-notation keys to a nested JSON object.
+ * { 'home.notes': 'Notes' } → { home: { notes: 'Notes' } }
+ */
+function unflattenKeys(flat) {
+  const result = {};
+  for (const [dotKey, value] of Object.entries(flat)) {
+    const parts = dotKey.split('.');
+    let obj = result;
+    for (let i = 0; i < parts.length - 1; i++) {
+      if (typeof obj[parts[i]] !== 'object' || obj[parts[i]] === null) {
+        obj[parts[i]] = {};
+      }
+      obj = obj[parts[i]];
+    }
+    obj[parts[parts.length - 1]] = value;
+  }
+  return result;
+}
+
+/**
+ * Load an existing locale file and return flat dot-notation keys.
+ * Handles both nested JSON (vue-i18n standard) and legacy flat format.
  */
 export function loadLocale(localeDir, langCode) {
   const filePath = join(localeDir, `${langCode}.json`);
   if (existsSync(filePath)) {
     try {
-      return JSON.parse(readFileSync(filePath, 'utf-8'));
+      const raw = JSON.parse(readFileSync(filePath, 'utf-8'));
+      // Flatten nested objects to dot-notation for internal use
+      return flattenKeys(raw);
     } catch {
       return {};
     }
@@ -41,22 +82,24 @@ export function loadLocale(localeDir, langCode) {
 
 /**
  * Save a locale file, merging with existing keys.
+ * Writes nested JSON (standard for vue-i18n and react-i18next).
  */
-export function saveLocale(localeDir, langCode, newEntries) {
-  mkdirSync(localeDir, { recursive: true });
-
-  const filePath = join(localeDir, `${langCode}.json`);
-  const existing = loadLocale(localeDir, langCode);
-
-  // Merge: new entries take precedence for new keys,
-  // but don't overwrite existing translations (idempotent)
+export function saveLocale(localeDir, langCode, newEntries) {
+  mkdirSync(localeDir, { recursive: true });
+
+  const filePath = join(localeDir, `${langCode}.json`);
+  const existing = loadLocale(localeDir, langCode); // already flat
+
+  // Merge: don't overwrite existing translations
   const merged = { ...existing };
-  for (const [key, value] of Object.entries(newEntries)) {
-    if (!(key in merged)) {
-      merged[key] = value;
-    }
-  }
-
-  writeFileSync(filePath, JSON.stringify(merged, null, 2) + '\n', 'utf-8');
-  return filePath;
-}
+  for (const [key, value] of Object.entries(newEntries)) {
+    if (!(key in merged)) {
+      merged[key] = value;
+    }
+  }
+
+  // Write as nested JSON for i18n library compatibility
+  const nested = unflattenKeys(merged);
+  writeFileSync(filePath, JSON.stringify(nested, null, 2) + '\n', 'utf-8');
+  return filePath;
+}

package/src/index.js

@@ -165,6 +165,9 @@ export async function translateAllFiles(files, opts) {
   const allTranslations = { ...existingTarget, ...newTranslations };
 
   // Phase 4 — write files
+  if (!opts.dryRun) {
+    console.log(`  → Locale dir: ${resolvedLocaleDir}`);
+  }
   const results = [];
   for (const parseResult of parsed) {
     try {
@@ -174,7 +177,7 @@ export async function translateAllFiles(files, opts) {
       });
       results.push(r);
     } catch (err) {
-      if (verbose) console.error(`  Write error ${parseResult.filePath}: ${err.message}`);
+      console.error(`  ✗ Write error ${relative(cwd, parseResult.filePath)}: ${err.message}`);
       results.push({ count: 0, skipped: 0, relativePath: relative(cwd, parseResult.filePath) });
     }
   }

package/src/parsers/html.js

@@ -1,6 +1,6 @@
 import MagicString from 'magic-string';
 import { parse, NodeTypes } from '@vue/compiler-dom';
-import { textKey, isTranslatable } from '../utils.js';
+import { contextKey, isTranslatable } from '../utils.js';
 
 const ATTR_WHITELIST = new Set([
   'title',
@@ -82,7 +82,7 @@ export function parseHtml(source, filePath, project) {
       const marker = `data-i18n-${name}`;
       if (openTagText.includes(marker)) continue;
 
-      const key = textKey(value);
+      const key = contextKey(value, filePath);
       s.appendRight(prop.loc.end.offset, ` ${marker}="${key}"`);
       extracted.push({ key, text: value, context: `html-attr-${name}` });
     }
@@ -98,7 +98,7 @@ export function parseHtml(source, filePath, project) {
 
         const marker = tag === 'title' ? 'data-i18n-title' : 'data-i18n';
         if (!openTagText.includes(marker) && isTranslatable(plain)) {
-          const key = textKey(text);
+          const key = contextKey(text, filePath);
           s.appendLeft(openTagEnd, ` ${marker}="${key}"`);
           extracted.push({ key, text, context: `html-inner-${tag}` });
         }

package/src/parsers/js.js

@@ -2,7 +2,7 @@ import * as babelParser from '@babel/parser';
 import _traverse from '@babel/traverse';
 import * as t from '@babel/types';
 import MagicString from 'magic-string';
-import { textKey, isTranslatable } from '../utils.js';
+import { contextKey, isTranslatable } from '../utils.js';
 
 const traverse = _traverse.default || _traverse;
 
@@ -55,7 +55,7 @@ export function parseJs(source, filePath, project) {
 
       if (!translatableKeys.has(keyName)) return;
 
-      const key = textKey(valueNode.value);
+      const key = contextKey(valueNode.value, filePath);
       const tFunc = project.type === 'vue' ? `this.$t('${key}')` : `t('${key}')`;
 
       s.overwrite(valueNode.start, valueNode.end, tFunc);
@@ -80,7 +80,7 @@ export function parseJs(source, filePath, project) {
       if (['alert', 'confirm', 'prompt'].includes(calleeName)) {
         const arg = path.node.arguments[0];
         if (arg && arg.type === 'StringLiteral' && isTranslatable(arg.value)) {
-          const key = textKey(arg.value);
+          const key = contextKey(arg.value, filePath);
           const tFunc = project.type === 'vue' ? `this.$t('${key}')` : `t('${key}')`;
           s.overwrite(arg.start, arg.end, tFunc);
           extracted.push({ key, text: arg.value, context: 'js-call' });
@@ -106,7 +106,7 @@ export function parseJs(source, filePath, project) {
         ]);
 
         if (domProps.has(propName)) {
-          const key = textKey(right.value);
+          const key = contextKey(right.value, filePath);
           const tFunc = project.type === 'vanilla'
             ? `i18n.t('${key}')`
             : project.type === 'vue'

package/src/parsers/react.js

@@ -1,7 +1,7 @@
 import * as babelParser from '@babel/parser';
 import _traverse from '@babel/traverse';
 import MagicString from 'magic-string';
-import { textKey, isTranslatable } from '../utils.js';
+import { contextKey, isTranslatable } from '../utils.js';
 
 // Handle ESM default export quirks
 const traverse = _traverse.default || _traverse;
@@ -78,7 +78,7 @@ export function parseReact(source, filePath) {
       const text = path.node.value.trim();
       if (!isTranslatable(text)) return;
 
-      const key = textKey(text);
+      const key = contextKey(text, filePath);
       const { start, end } = path.node;
       const original = path.node.value;
       const leadingWs = original.match(/^(\s*)/)[1];
@@ -102,7 +102,7 @@ export function parseReact(source, filePath) {
       if (!isTranslatable(text)) return;
       if (!ATTR_WHITELIST.has(name) && text.length < 3) return;
 
-      const key = textKey(text);
+      const key = contextKey(text, filePath);
       s.overwrite(path.node.start, path.node.end, `${name}={t('${key}')}`);
       extracted.push({ key, text, context: `jsx-attr-${name}` });
 
@@ -117,7 +117,7 @@ export function parseReact(source, filePath) {
 
       const arg = path.node.arguments[0];
       if (arg?.type === 'StringLiteral' && isTranslatable(arg.value)) {
-        const key = textKey(arg.value);
+        const key = contextKey(arg.value, filePath);
         s.overwrite(arg.start, arg.end, `t('${key}')`);
         extracted.push({ key, text: arg.value, context: 'call-arg' });
       }

package/src/parsers/vue.js

@@ -1,10 +1,7 @@
 import * as compiler from '@vue/compiler-dom';
 import MagicString from 'magic-string';
-import { textKey, isTranslatable, parseInterpolation } from '../utils.js';
+import { contextKey, isTranslatable } from '../utils.js';
 
-/**
- * Non-translatable attribute names.
- */
 const ATTR_BLACKLIST = new Set([
   'id', 'class', 'style', 'src', 'href', 'ref', 'key', 'is',
   'v-model', 'v-bind', 'v-on', 'v-if', 'v-else', 'v-else-if',
@@ -17,195 +14,238 @@ const ATTR_BLACKLIST = new Set([
   'xmlns:xlink', 'xlink:href', 'data-testid', 'data-cy',
 ]);
 
-/**
- * Translatable attribute names.
- */
 const ATTR_WHITELIST = new Set([
   'title', 'placeholder', 'label', 'alt', 'aria-label',
   'aria-placeholder', 'aria-description', 'aria-roledescription',
 ]);
 
+/**
+ * Detect which t-function call to emit in templates.
+ *
+ * Rules:
+ *  - If <script setup> and file already destructures `t` from a composable
+ *    → use  t('key')          (matches user's existing pattern)
+ *  - If <script setup> but no `t` yet
+ *    → use  t('key')   AND inject `const { t } = useI18n()` into script
+ *  - Options API (no setup)
+ *    → use  $t('key')         (global plugin property)
+ */
+function detectTStyle(source) {
+  const isSetup = /<script\b[^>]*\bsetup\b/i.test(source);
+
+  // Already has:  const { t } = ...   or   const { t, ... } = ...
+  const hasT = /const\s*\{[^}]*\bt\b[^}]*\}\s*=/.test(source);
+
+  return { isSetup, hasT };
+}
+
 /**
  * Parse a .vue file and extract translatable strings.
- * Returns the modified source and the list of extracted strings.
  */
 export function parseVue(source, filePath) {
-  const extracted = []; // {key, text, context}
+  const extracted = [];
   const s = new MagicString(source);
-  let modified = false;
 
-  // Parse template section
+  const { isSetup, hasT } = detectTStyle(source);
+
+  // In templates: use t() for Composition API, $t() for Options API
+  const tpl = (key) => (isSetup || hasT) ? `t('${key}')` : `$t('${key}')`;
+  // In scripts: use t() for setup, this.$t() for options
+  const scr = (key) => isSetup ? `t('${key}')` : `this.$t('${key}')`;
+
+  // ── Template ────────────────────────────────────────────────────────────────
   const templateMatch = source.match(/<template\b[^>]*>([\s\S]*?)<\/template>/);
   if (templateMatch) {
-    const templateStart = source.indexOf(templateMatch[0]);
     const templateContent = templateMatch[1];
-    const templateOffset = templateStart + templateMatch[0].indexOf(templateContent);
+    const templateOffset =
+      source.indexOf(templateMatch[0]) + templateMatch[0].indexOf(templateContent);
 
     try {
-      const ast = compiler.parse(templateContent, {
-        comments: true,
-        getTextMode: () => 0,
-      });
-
-      walkTemplate(ast.children, s, templateOffset, extracted);
-      modified = extracted.length > 0;
-    } catch (err) {
-      // If Vue parser fails, fall back to regex-based extraction for template
-      extractTemplateRegex(source, s, extracted);
-      modified = extracted.length > 0;
+      const ast = compiler.parse(templateContent, { comments: true, getTextMode: () => 0 });
+      walkTemplate(ast.children, s, templateOffset, extracted, filePath, tpl);
+    } catch {
+      extractTemplateRegex(source, s, extracted, filePath, tpl);
     }
   }
 
-  // Parse script section for string literals
+  // ── Script ──────────────────────────────────────────────────────────────────
   const scriptMatch = source.match(/<script\b[^>]*>([\s\S]*?)<\/script>/);
   if (scriptMatch) {
-    const scriptStart = source.indexOf(scriptMatch[0]);
     const scriptContent = scriptMatch[1];
-    const scriptOffset = scriptStart + scriptMatch[0].indexOf(scriptContent);
-    const isSetup = /<script\b[^>]*setup[^>]*>/.test(source);
+    const scriptOffset =
+      source.indexOf(scriptMatch[0]) + scriptMatch[0].indexOf(scriptContent);
+    extractScriptStrings(scriptContent, s, scriptOffset, extracted, filePath, scr);
+  }
 
-    extractScriptStrings(scriptContent, s, scriptOffset, extracted, isSetup);
+  // ── Inject `const { t } = useI18n()` if setup but t not yet declared ────────
+  if (extracted.length > 0 && isSetup && !hasT) {
+    const scriptSetupMatch = source.match(/(<script\b[^>]*\bsetup\b[^>]*>)([\s\S]*?)<\/script>/i);
+    if (scriptSetupMatch) {
+      const insertAt =
+        source.indexOf(scriptSetupMatch[0]) + scriptSetupMatch[1].length;
+      const needsImport = !source.includes('useI18n');
+      const importLine = needsImport ? `import { useI18n } from 'vue-i18n';\n` : '';
+      s.appendRight(insertAt, `\n${importLine}const { t } = useI18n();\n`);
+    }
   }
 
   return {
-    source: modified || extracted.length > 0 ? s.toString() : source,
+    source: extracted.length > 0 ? s.toString() : source,
     extracted,
-    modified: modified || extracted.length > 0,
+    modified: extracted.length > 0,
   };
 }
 
-function walkTemplate(nodes, s, baseOffset, extracted) {
+// ── Template walker ───────────────────────────────────────────────────────────
+
+function walkTemplate(nodes, s, baseOffset, extracted, filePath, tpl) {
   for (const node of nodes) {
-    // Type 2 = Text
+    // Text node (type 2)
     if (node.type === 2) {
       const text = node.content.trim();
       if (isTranslatable(text)) {
-        const key = textKey(text);
         const start = baseOffset + node.loc.start.offset;
-        const end = baseOffset + node.loc.end.offset;
+        const end   = baseOffset + node.loc.end.offset;
 
-        // Check if already wrapped in $t()
         if (!isAlreadyWrapped(s.original, start, end)) {
-          // Preserve leading/trailing whitespace
-          const originalText = node.content;
-          const leadingWs = originalText.match(/^(\s*)/)[1];
-          const trailingWs = originalText.match(/(\s*)$/)[1];
-
-          s.overwrite(start, end, `${leadingWs}{{ $t('${key}') }}${trailingWs}`);
+          const key = contextKey(text, filePath);
+          const orig = node.content;
+          const lws  = orig.match(/^(\s*)/)[1];
+          const tws  = orig.match(/(\s*)$/)[1];
+          s.overwrite(start, end, `${lws}{{ ${tpl(key)} }}${tws}`);
           extracted.push({ key, text, context: 'template-text' });
         }
       }
     }
 
-    // Type 1 = Element
+    // Element (type 1) — check translatable attributes, then recurse
     if (node.type === 1) {
-      // Check translatable attributes
-      if (node.props) {
-        for (const prop of node.props) {
-          // Type 6 = Attribute (static)
-          if (prop.type === 6 && prop.value) {
-            const attrName = prop.name.toLowerCase();
-
-            if (ATTR_WHITELIST.has(attrName) && isTranslatable(prop.value.content)) {
-              const text = prop.value.content;
-              const key = textKey(text);
+      for (const prop of node.props ?? []) {
+        if (prop.type === 6 && prop.value) {
+          const attrName = prop.name.toLowerCase();
+          if (ATTR_WHITELIST.has(attrName) && isTranslatable(prop.value.content)) {
+            const text = prop.value.content;
+            if (!ATTR_BLACKLIST.has(attrName)) {
+              const key      = contextKey(text, filePath);
               const attrStart = baseOffset + prop.loc.start.offset;
-              const attrEnd = baseOffset + prop.loc.end.offset;
-
-              // Convert static attribute to v-bind with $t()
-              s.overwrite(attrStart, attrEnd, `:${attrName}="$t('${key}')"`);
+              const attrEnd   = baseOffset + prop.loc.end.offset;
+              s.overwrite(attrStart, attrEnd, `:${attrName}="${tpl(key)}"`);
               extracted.push({ key, text, context: `template-attr-${attrName}` });
             }
           }
         }
       }
-
-      // Recurse into children
-      if (node.children) {
-        walkTemplate(node.children, s, baseOffset, extracted);
-      }
+      if (node.children) walkTemplate(node.children, s, baseOffset, extracted, filePath, tpl);
     }
 
-    // Type 5 = Interpolation ({{ expr }})
-    if (node.type === 5 && node.content) {
-      // Check for compound expressions that contain string literals
-      // e.g., {{ isError ? 'Failed' : 'Success' }}
-      // We only extract simple string content, not expressions
-    }
-
-    // Type 8 = CompoundExpression — skip
-    // Type 11 = ForNode — recurse into children
+    // ForNode (type 11)
     if (node.type === 11 && node.children) {
-      walkTemplate(node.children, s, baseOffset, extracted);
+      walkTemplate(node.children, s, baseOffset, extracted, filePath, tpl);
     }
-    // Type 9 = IfNode — recurse into branches
+
+    // IfNode (type 9) — walk branches
     if (node.type === 9 && node.branches) {
       for (const branch of node.branches) {
-        if (branch.children) {
-          walkTemplate(branch.children, s, baseOffset, extracted);
-        }
+        if (branch.children) walkTemplate(branch.children, s, baseOffset, extracted, filePath, tpl);
       }
     }
   }
 }
 
-function extractScriptStrings(scriptContent, s, baseOffset, extracted, isSetup) {
-  // Match string literals that look like translatable text in common patterns:
-  // - alert('text'), confirm('text')
-  // - title: 'text', label: 'text', placeholder: 'text', message: 'text'
-  // - toast('text'), notify('text')
-  // - error/success/warning message strings
+// ── Script string extractor ───────────────────────────────────────────────────
 
-  const patterns = [
-    // Function calls: alert('...'), confirm('...'), toast('...'), notify('...')
+function extractScriptStrings(scriptContent, s, baseOffset, extracted, filePath, scr) {
+  // Pattern A: alert/confirm/toast/notify calls  →  match[2]=quote, match[3]=text
+  // Pattern B: UI object property string values  →  match[2]=quote, match[3]=text
+  const patternsAB = [
     /\b(alert|confirm|toast|notify|message\.(?:success|error|warning|info))\s*\(\s*(['"`])((?:(?!\2).)+)\2\s*\)/g,
-    // Object properties: title: '...', label: '...', message: '...'
-    /\b(title|label|placeholder|message|text|description|tooltip|hint|caption|header|subtitle|errorMessage|successMessage)\s*:\s*(['"`])((?:(?!\2).)+)\2/g,
+    /\b(title|label|placeholder|message|text|description|tooltip|hint|caption|header|subtitle|errorMessage|successMessage|emptyText|noData|loadingText|buttonText|confirmText|cancelText|successText|failText|warningText|helperText|hintText)\s*:\s*(['"`])((?:(?!\2).)+)\2/g,
   ];
 
-  for (const pattern of patterns) {
+  for (const pattern of patternsAB) {
     let match;
     while ((match = pattern.exec(scriptContent)) !== null) {
       const text = match[3];
-      if (isTranslatable(text) && text.length > 1) {
-        const key = textKey(text);
-        const fullMatchStart = baseOffset + match.index;
-        const quoteChar = match[2];
-        const textStart = baseOffset + match.index + match[0].indexOf(quoteChar + text);
-        const textEnd = textStart + text.length + 2; // +2 for quotes
+      if (!isTranslatable(text) || text.length <= 1) continue;
+      const quoteChar = match[2];
+      const relPos = match.index + match[0].indexOf(quoteChar + text);
+      if (isAlreadyWrappedScript(scriptContent, relPos)) continue;
+      const key      = contextKey(text, filePath);
+      const textStart = baseOffset + relPos;
+      const textEnd   = textStart + text.length + 2;
+      s.overwrite(textStart, textEnd, scr(key));
+      extracted.push({ key, text, context: 'script' });
+    }
+  }
 
-        const tCall = isSetup ? `t('${key}')` : `this.$t('${key}')`;
+  // Pattern C: ref('string') / ref("string")  →  match[1]=quote, match[2]=text
+  const refPattern = /\bref\s*\(\s*(['"`])((?:(?!\1)[^\\]|\\.)+)\1\s*\)/g;
+  {
+    let match;
+    while ((match = refPattern.exec(scriptContent)) !== null) {
+      const text = match[2];
+      if (!isTranslatable(text) || text.length <= 1) continue;
+      const quoteChar = match[1];
+      const innerStr  = quoteChar + text + quoteChar;
+      const relPos    = match.index + match[0].indexOf(innerStr);
+      if (isAlreadyWrappedScript(scriptContent, relPos)) continue;
+      const key      = contextKey(text, filePath);
+      const textStart = baseOffset + relPos;
+      const textEnd   = textStart + innerStr.length;
+      s.overwrite(textStart, textEnd, scr(key));
+      extracted.push({ key, text, context: 'script-ref' });
+    }
+  }
 
-        s.overwrite(textStart, textEnd, tCall);
-        extracted.push({ key, text, context: 'script' });
-      }
+  // Pattern D: computed(() => 'string')  →  match[1]=quote, match[2]=text
+  const computedPattern = /\bcomputed\s*\(\s*\(\s*\)\s*=>\s*(['"`])((?:(?!\1)[^\\]|\\.)+)\1\s*\)/g;
+  {
+    let match;
+    while ((match = computedPattern.exec(scriptContent)) !== null) {
+      const text = match[2];
+      if (!isTranslatable(text) || text.length <= 1) continue;
+      const quoteChar = match[1];
+      const innerStr  = quoteChar + text + quoteChar;
+      const relPos    = match.index + match[0].indexOf(innerStr);
+      if (isAlreadyWrappedScript(scriptContent, relPos)) continue;
+      const key      = contextKey(text, filePath);
+      const textStart = baseOffset + relPos;
+      const textEnd   = textStart + innerStr.length;
+      s.overwrite(textStart, textEnd, scr(key));
+      extracted.push({ key, text, context: 'script-computed' });
     }
   }
 }
 
+function isAlreadyWrappedScript(scriptContent, pos) {
+  const before = scriptContent.slice(Math.max(0, pos - 30), pos);
+  return /\$?t\s*\(\s*$/.test(before);
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
 function isAlreadyWrapped(source, start, end) {
-  // Check if the text is already inside a $t() call or {{ $t(...) }}
-  const before = source.slice(Math.max(0, start - 20), start);
-  return /\$t\s*\(\s*['"]/.test(before) || /t\s*\(\s*['"]/.test(before);
+  // Look back 25 chars for an open t( or $t( call — node is inside an interpolation
+  const before = source.slice(Math.max(0, start - 25), start);
+  return /\$?t\s*\(\s*['"]/.test(before);
 }
 
-function extractTemplateRegex(source, s, extracted) {
-  // Fallback regex extraction for when the Vue parser fails
-  const textPattern = />([^<]+)</g;
+function extractTemplateRegex(source, s, extracted, filePath, tpl) {
+  const pattern = />([^<]+)</g;
   let match;
-  while ((match = textPattern.exec(source)) !== null) {
+  while ((match = pattern.exec(source)) !== null) {
     const text = match[1].trim();
     if (isTranslatable(text)) {
-      const key = textKey(text);
       const textStart = match.index + 1;
-      const textEnd = textStart + match[1].length;
+      const textEnd   = textStart + match[1].length;
       if (!isAlreadyWrapped(source, textStart, textEnd)) {
-        const original = match[1];
-        const leadingWs = original.match(/^(\s*)/)[1];
-        const trailingWs = original.match(/(\s*)$/)[1];
-        s.overwrite(textStart, textEnd, `${leadingWs}{{ $t('${key}') }}${trailingWs}`);
+        const key  = contextKey(text, filePath);
+        const orig = match[1];
+        const lws  = orig.match(/^(\s*)/)[1];
+        const tws  = orig.match(/(\s*)$/)[1];
+        s.overwrite(textStart, textEnd, `${lws}{{ ${tpl(key)} }}${tws}`);
         extracted.push({ key, text, context: 'template-text' });
       }
     }
   }
-}
+}

package/src/utils.js

@@ -1,4 +1,16 @@
 import { createHash } from 'crypto';
+import { basename, extname } from 'path';
+
+// Words too generic to use as the sole semantic component of a key
+const STOP_WORDS = new Set([
+  'a', 'an', 'the', 'is', 'are', 'was', 'were', 'be', 'been', 'being',
+  'have', 'has', 'had', 'do', 'does', 'did', 'will', 'would', 'shall',
+  'should', 'may', 'might', 'must', 'can', 'could',
+  'to', 'for', 'and', 'or', 'but', 'of', 'in', 'on', 'at', 'by',
+  'as', 'if', 'its', 'it', 'this', 'that', 'these', 'those',
+  'my', 'your', 'our', 'their', 'with', 'from', 'up', 'about',
+  'no', 'not', 'so',
+]);
 
 /**
  * Generate a readable, slug-based i18n key from a string.
@@ -30,7 +42,52 @@ export function textKey(text) {
 }
 
 /**
- * @deprecated Use textKey() instead. Kept for internal backward compat.
+ * Generate a context-aware i18n key using the component name as namespace
+ * and key content words as the slug.
+ *
+ * "Notes"           in HomeView.vue  → home.notes
+ * "Quick Note"      in HomeView.vue  → home.quickNote
+ * "View livestock"  in HomeView.vue  → home.viewLivestock
+ * "Submit"          in LoginForm.vue → loginForm.submit
+ * "你好"             in App.vue       → app.key_3d2a1f
+ *
+ * @param {string} text     The source string to key
+ * @param {string} filePath Absolute or relative path of the source file
+ */
+export function contextKey(text, filePath) {
+  const trimmed = text.trim();
+
+  // ── Namespace: derive from filename ──────────────────────────────────────
+  const fileName = basename(filePath, extname(filePath));
+  // Strip common Vue/React suffixes: HomeView → Home, UserCard → User, etc.
+  const stripped = fileName.replace(
+    /(?:View|Component|Page|Screen|Modal|Dialog|Card|Panel|Widget|Layout|Container)$/,
+    ''
+  ) || fileName;
+  // camelCase namespace: "UserProfile" → "userProfile", "home" → "home"
+  const ns = stripped[0].toLowerCase() + stripped.slice(1);
+
+  // ── Slug: 1-3 meaningful words in camelCase ───────────────────────────────
+  const words = trimmed
+    .replace(/[^\w\s]/g, ' ')
+    .split(/\s+/)
+    .map((w) => w.toLowerCase())
+    .filter((w) => w.length >= 2 && /[a-z]/.test(w) && !STOP_WORDS.has(w));
+
+  if (!words.length) {
+    // Non-Latin scripts, emoji, or all stop words — fall back to hash suffix
+    const hash = createHash('sha256').update(trimmed).digest('hex').slice(0, 6);
+    return `${ns}.key${hash}`;
+  }
+
+  const slug =
+    words[0] + words.slice(1, 3).map((w) => w[0].toUpperCase() + w.slice(1)).join('');
+
+  return `${ns}.${slug}`;
+}
+
+/**
+ * @deprecated Use contextKey() for new code. textKey() kept for non-file contexts.
  */
 export const hashKey = textKey;