i18n-lens-language-server 0.12.0 → 0.14.0

package/README.md

@@ -9,10 +9,11 @@ Zed extension plus Language Server for Vue, TypeScript, TSX, JavaScript and JSX.
 - Hover: show all locale values for a key
 - Diagnostics: report missing keys, missing locale entries, mismatched interpolation params, and (on locale files) keys whose params differ across languages
 - Optional raw-text diagnostics: flag likely untranslated Vue/HTML template text and selected user-facing attributes
-- Quick fixes: add missing / remove unused interpolation params on supported i18n calls, and create a missing key in every locale file that lacks it
-- Completion: suggest existing i18n keys with default locale text
+- Quick fixes: add missing / remove unused interpolation params, and create missing keys in unambiguous JSON locale targets using versioned edits
+- Completion: suggest existing i18n keys with default locale text only inside supported i18n key positions
 - Definition: jump from a source key to its locale definition; when several locales define the key, pick which language file to open
-- References: from a key in a locale file (or a source usage), find every place the key is used across the project's source code
+- References: from a locale definition or source usage, find references within the same project/package context, including open source files not yet saved to disk
+- Recursive locale directories: nested JSON, TS, and JS files map to dot-separated namespaces, with `index` files contributing to their parent namespace
 
 ## Installation
 
@@ -69,6 +70,8 @@ To open a specific language file, use Go to Definition (Ctrl/Cmd+click or F12) o
 
 Diagnostics refresh automatically when loaded locale files or locale directories change, so editing translation files should update warnings/errors without restarting the extension.
 
+Open locale documents take precedence over disk contents. Opening, changing, or closing an existing locale file refreshes translations and diagnostics without requiring a save.
+
 Diagnostics distinguish between these cases:
 
 - If a key is missing from every loaded locale, it is reported as an error.
@@ -106,6 +109,17 @@ Comments, `script`/`style`, Vue custom blocks, interpolations (`{{ ... }}`), tra
 There is no Babel/JavaScript/TypeScript/JSX string analysis, workspace-wide scan, automatic extraction or raw-text quick fix. Only open Vue/HTML buffers receive these warnings. The parser is tolerant of incomplete markup, not a full Vue compiler; complex or malformed templates can be missed. Existing key/parameter diagnostics and quick fixes are unchanged.
 
 For local development, HTML registration in `extension.toml` requires reinstalling the dev extension in Zed, then running `scripts/deploy-local.ps1` again and restarting the language server. Updating only the server does not register HTML buffers.
+## Creating missing keys safely
+
+The missing-key quick fix supports a single JSON file per locale and directory layouts such as `locales/en/common.json`. For `t('common.submit')`, it inserts `submit` into `common.json`, without duplicating the `common.` prefix. `index.json` has no file-stem prefix.
+
+- Edits use the current open document text and version, preserve unrelated content and line endings, and change only the necessary text rather than replacing the entire file.
+- If a target namespace file is missing, the server can create it when another locale establishes the corresponding JSON namespace layout. It does not invent an unknown namespace layout or overwrite a file that appears after the action was requested.
+- Ambiguous layouts (for example, both `common.json` and `common.ts`, overlapping index/namespace ownership including empty namespace objects, or multiple backing directories) do not receive a guessed edit. Invalid JSON, duplicate properties, and scalar/object path conflicts are also refused.
+- A multi-locale diagnostic receives a creation action only when all remaining missing locales can be repaired safely. TS/JS module writes and JSONC locale loading/writes are not supported.
+- Quick fixes require LSP `workspace.workspaceEdit.documentChanges` support. Creating a file additionally requires the `create` resource operation. Existing-file edits use the open document version, or `null` for closed files; the server cannot version-check external changes to closed files.
+
+Recognition skips calls inside comments and ordinary strings, and does not treat a concatenated key such as `t('prefix.' + name)` as a static key. Vue directive expressions, JSX expressions, and calls inside template-literal interpolations remain supported. Recognition is lexical, not full framework binding or scope analysis.
 
 ## Project configuration
 
@@ -207,6 +221,21 @@ src/locales/ja-JP/common.json
 
 A file named `common.json` contributes keys with the `common.` prefix. A file named `index.json` contributes keys without an `index.` prefix.
 
+Locale directories are scanned recursively. Subdirectories contribute to the namespace:
+
+```text
+src/locales/en-US/system/user.json       -> system.user.*
+src/locales/en-US/system/index.json      -> system.*
+src/locales/en-US/system/forms/fields.ts -> system.forms.fields.*
+src/locales/en-US/index/index.json       -> index.*
+```
+
+Nested JSON, TS, and JS locale files support translation previews, definition, references, and unsaved buffer updates. Adding files in nested directories refreshes translations automatically. Missing-key quick fixes retain the existing namespace directory layout when the target is unambiguous and its parent directory exists.
+
+If `localeDirs` overlap, an explicitly configured nested root is excluded from its ancestor's recursive scan, regardless of configuration order or nesting depth. For example, with `["locales", "locales/modules/features"]`, `locales/modules/features/en/user.json` belongs to locale `en` with keys `user.*`, not locale `modules`. Intermediate directories without locale files are watched for new files but do not count as locales. Empty locale files still count as locales and report missing keys.
+
+Top-level TS/JS modules such as `locales/en.ts` are also loaded, without adding an `en.` prefix. Directory modules such as `locales/en/common.ts` retain the `common.` prefix; `index.ts` has no file-stem prefix. Modules are parsed statically, never executed. Their definitions support Find References and cross-language parameter diagnostics, not source-code completions or inlay hints. TS/JS key positioning remains best-effort rather than a full syntax-tree analysis.
+
 ## Monorepo workspaces
 
 For pnpm/turborepo and other monorepos, put `.zed/i18nlensrc.json` under the workspace root and add `packages` entries:
@@ -230,6 +259,8 @@ For pnpm/turborepo and other monorepos, put `.zed/i18nlensrc.json` under the wor
 
 When a document is opened, I18n Lens selects the package whose `root` is the longest path prefix of that document. `localeDirs` inside a package are resolved relative to that package root, so `apps/web/src/locales` and `packages/admin/src/i18n` are indexed independently. Package entries inherit root-level `defaultLocale`, `localeDirs`, `inlayHints`, and `rawTextDiagnostics` unless they override them.
 
+Find References excludes separately configured nested package roots and locale modules, so identical keys in independent packages are not mixed. The existing source scanner is bounded at approximately 5,000 files; its results are not a project-wide completeness guarantee for larger workspaces.
+
 ## Local development
 
 Install dependencies:
@@ -244,6 +275,8 @@ Run tests:
 npm test
 ```
 
+The suite covers pure-function behavior plus real stdio LSP sessions in temporary workspaces, including dirty locale buffers, namespace file creation, client capabilities, and package-isolated references.
+
 The language server is published to npm as
 [`i18n-lens-language-server`](https://www.npmjs.com/package/i18n-lens-language-server).
 A Zed extension must not ship its language server, so the Rust shell installs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "i18n-lens-language-server",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "type": "module",
   "description": "Language server for configurable i18n inlay hints, hover, completion, diagnostics, definition, and references in Vue/TS/TSX/JS.",
   "license": "MIT",

package/server/core.js

@@ -303,22 +303,133 @@ function offsetToPosition(text, offset) {
 function makeRange(text, start, end) {
   return { start: offsetToPosition(text, start), end: offsetToPosition(text, end) };
 }
+// Lexical mask over mixed Vue/TS/JSX text: returns the sorted ranges that are
+// NOT real code — comments, plain strings, template-literal raw text, HTML
+// comments, and ordinary (non-directive) attribute values. Vue directive
+// attribute values (`:x="…"`, `v-x="…"`, `@x="…"`, `#x="…"`) and `${…}`
+// interpolations inside template literals stay transparent so real
+// expressions inside them are still scanned. Best-effort lexing only — no AST.
+function computeOpaqueRanges(text) {
+  const ranges = [];
+  const stack = [{ type: 'code' }];
+  const top = () => stack[stack.length - 1];
+  let i = 0;
+  while (i < text.length) {
+    const f = top();
+    const ch = text[i];
+    if (f.type === 'lineComment') {
+      if (ch === '\n') { ranges.push({ start: f.start, end: i }); stack.pop(); }
+      i++;
+      continue;
+    }
+    if (f.type === 'blockComment') {
+      if (ch === '*' && text[i + 1] === '/') { ranges.push({ start: f.start, end: i + 2 }); stack.pop(); i += 2; continue; }
+      i++;
+      continue;
+    }
+    if (f.type === 'htmlComment') {
+      if (ch === '-' && text[i + 1] === '-' && text[i + 2] === '>') { ranges.push({ start: f.start, end: i + 3 }); stack.pop(); i += 3; continue; }
+      i++;
+      continue;
+    }
+    if (f.type === 'string') {
+      if (ch === '\\') { i += 2; continue; }
+      if (ch === f.quote) { ranges.push({ start: f.start, end: i + 1 }); stack.pop(); }
+      i++;
+      continue;
+    }
+    if (f.type === 'template') {
+      if (ch === '\\') { i += 2; continue; }
+      if (ch === '`') { ranges.push({ start: f.start, end: i + 1 }); stack.pop(); i++; continue; }
+      if (ch === '$' && text[i + 1] === '{') {
+        ranges.push({ start: f.start, end: i });
+        stack.pop();
+        stack.push({ type: 'templateExpr', depth: 0 });
+        i += 2;
+        continue;
+      }
+      i++;
+      continue;
+    }
+
+    // code-like frames: code, templateExpr, attrExpr
+    if (f.type === 'attrExpr' && f.depth === 0 && ch === f.quote) { stack.pop(); i++; continue; }
+    if (ch === '{') {
+      if (f.type === 'templateExpr' || f.type === 'attrExpr') f.depth++;
+      i++;
+      continue;
+    }
+    if (ch === '}') {
+      if (f.type === 'templateExpr') {
+        if (f.depth === 0) { stack.pop(); stack.push({ type: 'template', start: i + 1 }); }
+        else f.depth--;
+      } else if (f.type === 'attrExpr' && f.depth > 0) f.depth--;
+      i++;
+      continue;
+    }
+    if (ch === '/' && text[i + 1] === '/') { stack.push({ type: 'lineComment', start: i }); i += 2; continue; }
+    if (ch === '/' && text[i + 1] === '*') { stack.push({ type: 'blockComment', start: i }); i += 2; continue; }
+    if (ch === '<' && text[i + 1] === '!' && text[i + 2] === '-' && text[i + 3] === '-') { stack.push({ type: 'htmlComment', start: i }); i += 4; continue; }
+    if (ch === '"' || ch === "'") {
+      if (f.type === 'code' && isAttrExprQuote(text, i)) stack.push({ type: 'attrExpr', quote: ch, depth: 0 });
+      else stack.push({ type: 'string', quote: ch, start: i });
+      i++;
+      continue;
+    }
+    if (ch === '`') { stack.push({ type: 'template', start: i }); i++; continue; }
+    i++;
+  }
+  while (stack.length > 1) {
+    const f = stack.pop();
+    if (f.start !== undefined) ranges.push({ start: f.start, end: text.length });
+  }
+  return ranges;
+}
+
+// A quote is a Vue directive attribute opener when preceded by `name=` where
+// name is `:foo`, `@foo`, `#foo`, `v-foo`, or `ns:foo` (v-on:, v-bind:, …).
+// Plain attributes (`title="…"`, JSX `attr="…"`) keep string semantics.
+function isAttrExprQuote(text, quoteOffset) {
+  const before = text.slice(Math.max(0, quoteOffset - 200), quoteOffset);
+  return /(?:^|[\s<"'`])(?:[:@#][\w.:[\]-]*|[\w-]+:[\w.:[\]-]*|v-[\w.:[\]-]*)\s*=\s*$/.test(before);
+}
+
+function isOpaque(ranges, offset) {
+  let lo = 0;
+  let hi = ranges.length - 1;
+  while (lo <= hi) {
+    const mid = (lo + hi) >> 1;
+    const r = ranges[mid];
+    if (offset < r.start) hi = mid - 1;
+    else if (offset >= r.end) lo = mid + 1;
+    else return true;
+  }
+  return false;
+}
+
 
 export function extractI18nKeys(text) {
   const found = [];
-  collectFunctionCallKeys(text, found);
-  collectFormatMessageKeys(text, found);
+  const opaque = computeOpaqueRanges(text);
+  collectFunctionCallKeys(text, found, opaque);
+  collectFormatMessageKeys(text, found, opaque);
   const patterns = [
     // <i18n-t keypath="key"> (Vue I18n) and <Trans i18nKey="key"> (react-i18next)
     /\b(?:keypath|i18nKey)\s*=\s*(['"])([A-Za-z0-9_.:-]+)\1/g,
     /\bv-t\s*=\s*"'([A-Za-z0-9_.:-]+)'"/g,
+    /\bv-t\s*=\s*'"([A-Za-z0-9_.:-]+)"'/g,
     /\bv-t\s*=\s*"\s*\{\s*path\s*:\s*(['"])([A-Za-z0-9_.:-]+)\1/g,
   ];
   for (const re of patterns) {
     let match;
     while ((match = re.exec(text))) {
+      const before = text[match.index - 1];
+      // Literal attribute only — bound directives (`:keypath`, `@`, `#`, `.prop`)
+      // hold expressions handled by the call scanner, not a literal key.
+      if (before !== undefined && /[\w:@#.-]/.test(before)) continue;
+      if (isOpaque(opaque, match.index)) continue;
       const key = match[2] || match[1];
-      const keyOffsetInMatch = match[0].indexOf(key);
+      const keyOffsetInMatch = match[0].lastIndexOf(key);
       const start = match.index + keyOffsetInMatch;
       const end = start + key.length;
       found.push({ key, range: makeRange(text, start, end), startOffset: start, endOffset: end });
@@ -328,15 +439,19 @@ export function extractI18nKeys(text) {
   return found;
 }
 
-function collectFunctionCallKeys(text, found) {
+function collectFunctionCallKeys(text, found, opaque) {
   // t/$t/tc/$tc/i18n.t/i18n.tc(...) — function calls, incl. Vue I18n plural tc
   const re = /(?:\x24tc?|\btc?|\bi18n\.tc?)\s*\(/g;
   let match;
   while ((match = re.exec(text))) {
     const parenOffset = re.lastIndex - 1;
+    if (/[\w$]/.test(text[match.index - 1] || '')) continue;
+    if (isOpaque(opaque, match.index)) continue;
     const callText = readParens(text, parenOffset);
     if (!callText) continue;
-    const keyMatch = callText.match(/^\(\s*(['"])([A-Za-z0-9_.:-]+)\1/);
+    // First arg must be exactly one string literal — dynamic keys like
+    // `t('prefix.' + name)` are skipped, never half-matched.
+    const keyMatch = callText.match(/^\(\s*(['"])([A-Za-z0-9_.:-]+)\1(?=\s*[,)])/);
     if (!keyMatch) continue;
     const key = keyMatch[2];
     const start = parenOffset + keyMatch[0].indexOf(key);
@@ -348,19 +463,21 @@ function collectFunctionCallKeys(text, found) {
   }
 }
 
-function collectFormatMessageKeys(text, found) {
+function collectFormatMessageKeys(text, found, opaque) {
   const re = /\bformatMessage\s*\(/g;
   let match;
   while ((match = re.exec(text))) {
+    if (/[\w$]/.test(text[match.index - 1] || '')) continue;
+    if (isOpaque(opaque, match.index)) continue;
     const parenOffset = re.lastIndex - 1;
     const callText = readParens(text, parenOffset);
     if (!callText) continue;
     const args = splitArgsWithOffsets(callText.slice(1, -1));
     const idArg = args[0]?.text || '';
-    const keyMatch = idArg.match(/\bid\s*:\s*(['"])([A-Za-z0-9_.:-]+)\1/);
+    const keyMatch = idArg.match(/\bid\s*:\s*(['"])([A-Za-z0-9_.:-]+)\1(?=\s*[,}])/);
     if (!keyMatch) continue;
     const key = keyMatch[2];
-    const start = parenOffset + 1 + idArg.indexOf(key);
+    const start = parenOffset + 1 + args[0].start + keyMatch.index + keyMatch[0].lastIndexOf(key);
     const end = start + key.length;
     const paramsEdit = getParamsEdit(args.slice(1), parenOffset + 1, parenOffset + callText.length - 1);
     const paramsObject = extractParamsObject(args.slice(1), parenOffset + 1);
@@ -382,6 +499,18 @@ function readParens(text, start) {
       else if (ch === quote) quote = '';
       continue;
     }
+    if (ch === '/' && text[i + 1] === '/') {
+      const end = text.indexOf('\n', i + 2);
+      if (end < 0) return undefined;
+      i = end;
+      continue;
+    }
+    if (ch === '/' && text[i + 1] === '*') {
+      const end = text.indexOf('*/', i + 2);
+      if (end < 0) return undefined;
+      i = end + 1;
+      continue;
+    }
     if (ch === '"' || ch === "'" || ch === '`') { quote = ch; continue; }
     if (ch === '(' || ch === '{' || ch === '[') depth++;
     else if (ch === ')' || ch === '}' || ch === ']') {
@@ -513,28 +642,23 @@ export function collectLocaleWatchPaths(localeCache, localeDirs = []) {
 
 export function findLocaleKeyTarget(locale, key, localeTexts = {}) {
   if (!locale || !Object.prototype.hasOwnProperty.call(locale.flat || {}, key)) return undefined;
-  const files = Array.isArray(locale.files) && locale.files.length
-    ? locale.files
-    : (locale.path ? [locale.path] : []);
-  const candidates = files
-    .map((filePath) => ({ filePath, lookupKey: lookupKeyForLocaleFile(locale, filePath, key) }))
-    .sort((a, b) => Number(a.lookupKey === key) - Number(b.lookupKey === key));
-
-  for (const candidate of candidates) {
-    const text = localeTexts[candidate.filePath];
-    if (!text) continue;
-    const position = /\.json$/i.test(candidate.filePath)
-      ? findJsonKeyLocation(text, candidate.lookupKey)
-      : findLocaleKeyLocation(text, candidate.lookupKey);
-    if (position) return { filePath: candidate.filePath, position };
-  }
-
-  const fallback = candidates[0];
-  return fallback ? { filePath: fallback.filePath } : undefined;
+  // Namespace specificity does not determine which file won during loading.
+  const filePath = locale.keyFiles?.[key];
+  if (!filePath) return undefined;
+  const lookupKey = lookupKeyForLocaleFile(locale, filePath, key);
+  if (lookupKey === undefined) return undefined;
+  const text = localeTexts[filePath];
+  const range = text ? localeKeyRange(text, lookupKey, /\.json$/i.test(filePath)) : undefined;
+  return range ? { filePath, position: range.start, range } : { filePath };
 }
 
 function lookupKeyForLocaleFile(locale, filePath, key) {
-  const isNestedLocaleFile = normalizeFsPath(locale.path) !== normalizeFsPath(filePath);
+  const prefix = locale.filePrefixes?.[filePath];
+  if (prefix !== undefined) {
+    if (!prefix) return key;
+    return key.startsWith(prefix + '.') ? key.slice(prefix.length + 1) : undefined;
+  }
+  const isNestedLocaleFile = !locale.topLevelFiles?.includes(filePath) && normalizeFsPath(locale.path) !== normalizeFsPath(filePath);
   const stem = fileStem(filePath);
   if (isNestedLocaleFile && stem && stem !== 'index' && key.startsWith(stem + '.')) return key.slice(stem.length + 1);
   return key;
@@ -638,16 +762,15 @@ export function getLocaleParamConsistency(key, locales) {
 export function getLocaleParamDiagnostics(locale, filePath, text, locales) {
   if (!locale?.flat) return [];
   const isJson = /\.json$/i.test(filePath);
+  const jsonRoot = isJson ? parseJsonStructure(text) || null : undefined;
   const diagnostics = [];
   for (const key of Object.keys(locale.flat)) {
     const consistency = getLocaleParamConsistency(key, locales);
     if (consistency.consistent) continue;
     const lookupKey = lookupKeyForLocaleFile(locale, filePath, key);
-    const position = isJson ? findJsonKeyLocation(text, lookupKey) : findLocaleKeyLocation(text, lookupKey);
-    if (!position) continue;
-    const leaf = lookupKey.split('.').at(-1);
-    const end = { line: position.line, character: position.character + leaf.length + (isJson ? 2 : 0) };
-    diagnostics.push(paramInconsistencyDiagnostic(key, { start: position, end }, consistency.perLocale));
+    if (lookupKey === undefined) continue;
+    const range = localeKeyRange(text, lookupKey, isJson, jsonRoot);
+    if (range) diagnostics.push(paramInconsistencyDiagnostic(key, range, consistency.perLocale));
   }
   return diagnostics;
 }
@@ -791,118 +914,163 @@ export function collectLocaleKeyTargets(locales, key, localeTexts = {}, defaultL
 export function localeKeyAtPosition(locale, filePath, text, position) {
   if (!locale || !locale.flat || !text || !position) return undefined;
   const isJson = /\.json$/i.test(filePath);
+  const jsonRoot = isJson ? parseJsonStructure(text) || null : undefined;
   let lineFallback;
   let lineFallbackCount = 0;
   for (const fullKey of Object.keys(locale.flat)) {
     const lookupKey = lookupKeyForLocaleFile(locale, filePath, fullKey);
-    const loc = isJson ? findJsonKeyLocation(text, lookupKey) : findLocaleKeyLocation(text, lookupKey);
-    if (!loc || loc.line !== position.line) continue;
-    const leaf = lookupKey.split('.').at(-1);
-    const tokenStart = loc.character;
-    const tokenEnd = tokenStart + leaf.length + (isJson ? 2 : 0);
-    if (position.character >= tokenStart && position.character <= tokenEnd) return fullKey;
+    if (lookupKey === undefined) continue;
+    const range = localeKeyRange(text, lookupKey, isJson, jsonRoot);
+    if (!range || range.start.line !== position.line) continue;
+    if (comparePosition(position, range.start) >= 0 && comparePosition(position, range.end) < 0) return fullKey;
     lineFallback = fullKey;
     lineFallbackCount++;
   }
-  return lineFallbackCount === 1 ? lineFallback : undefined;
+  return !isJson && lineFallbackCount === 1 ? lineFallback : undefined;
 }
 
 export function getCompletionPrefix(text, position) {
-  const offset = positionToOffset(text, position);
-  const before = text.slice(0, offset);
+  const before = text.slice(0, positionToOffset(text, position));
+  const opaque = computeOpaqueRanges(before);
   const patterns = [
-    /(?:\x24tc?|\btc?|\bi18n\.tc?)\(\s*['"]([A-Za-z0-9_.:-]*)$/,
+    /(?:\x24tc?|\btc?|\bi18n\.tc?)\s*\(\s*['"]([A-Za-z0-9_.:-]*)$/,
     /\bformatMessage\s*\(\s*\{[^}]*?\bid\s*:\s*['"]([A-Za-z0-9_.:-]*)$/,
     /\b(?:keypath|i18nKey)\s*=\s*['"]([A-Za-z0-9_.:-]*)$/,
-    /v-t\s*=\s*"'([A-Za-z0-9_.:-]*)$/,
+    /\bv-t\s*=\s*"'([A-Za-z0-9_.:-]*)$/,
+    /\bv-t\s*=\s*'\x22([A-Za-z0-9_.:-]*)$/,
+    /\bv-t\s*=\s*"\s*\{\s*path\s*:\s*['"]([A-Za-z0-9_.:-]*)$/,
   ];
   for (const re of patterns) {
     const match = before.match(re);
-    if (match) return match[1];
+    if (!match || isOpaque(opaque, match.index)) continue;
+    if (/[\w$:@#-]/.test(before[match.index - 1] || '')) continue;
+    return match[1];
   }
-  return '';
+  return undefined;
 }
 
 export function findJsonKeyLocation(jsonText, key) {
-  const parts = key.split('.');
-  let cursor = 0;
-  for (const part of parts) {
-    const re = new RegExp('"' + escapeRegExp(part) + '"\\s*:', 'g');
-    re.lastIndex = cursor;
-    const match = re.exec(jsonText);
-    if (!match) return undefined;
-    cursor = match.index + match[0].length;
-    if (part === parts[parts.length - 1]) return offsetToPosition(jsonText, match.index);
-  }
-  return undefined;
+  return localeKeyRange(jsonText, key, true)?.start;
 }
 
-// Surgically insert a dotted `key` into a JSON document, creating intermediate
-// objects as needed and preserving the rest of the file's formatting. Returns
-// the new text, or undefined if the JSON is unparseable or the key already exists.
-export function insertNestedJsonKey(jsonText, key, value = '') {
-  let root;
-  try { root = JSON.parse(jsonText); } catch { return undefined; }
-  if (!root || typeof root !== 'object' || Array.isArray(root)) return undefined;
-  if (getValueByKey(root, key) !== undefined) return undefined;
-
-  const parts = key.split('.');
-  let node = root;
-  let existingDepth = 0;
-  for (; existingDepth < parts.length - 1; existingDepth++) {
-    const next = node[parts[existingDepth]];
-    if (next && typeof next === 'object' && !Array.isArray(next)) node = next;
-    else break;
+function localeKeyRange(text, key, isJson, jsonRoot = isJson ? parseJsonStructure(text) : undefined) {
+  if (isJson) {
+    const property = findJsonProperty(jsonRoot, key.split('.'));
+    return property ? makeRange(text, property.start, property.end) : undefined;
   }
+  const start = findLocaleKeyLocation(text, key);
+  if (!start) return undefined;
+  const offset = positionToOffset(text, start);
+  const token = text.slice(offset).match(/^(?:'[^']*'|"[^"]*"|[\w$-]+)/);
+  return token ? makeRange(text, offset, offset + token[0].length) : undefined;
+}
 
-  const span = findJsonObjectSpan(jsonText, parts.slice(0, existingDepth));
-  if (!span) return undefined;
-
-  const unit = detectIndentUnit(jsonText);
-  const snippet = buildNestedProperty(parts.slice(existingDepth), value, unit.repeat(existingDepth + 1), unit);
-  const inner = jsonText.slice(span.openBrace + 1, span.contentEnd).trim();
-  if (inner.length === 0) {
-    return jsonText.slice(0, span.openBrace + 1) + '\n' + snippet + '\n' + unit.repeat(existingDepth) + jsonText.slice(span.closeBrace);
+// JSON.parse validates the grammar; this walk retains property-token and value
+// boundaries for edits. Maps avoid prototype keys and duplicate keys are refused.
+function parseJsonStructure(text) {
+  try { JSON.parse(text); } catch { return undefined; }
+  let offset = 0;
+  let duplicate = false;
+  const whitespace = () => { while (/\s/.test(text[offset] || '') && offset < text.length) offset++; };
+  function stringEnd() {
+    offset++;
+    while (offset < text.length) {
+      if (text[offset] === '\\') offset += 2;
+      else if (text[offset++] === '"') break;
+    }
+  }
+  function value() {
+    whitespace();
+    const start = offset;
+    const properties = text[offset] === '{' ? new Map() : undefined;
+    if (properties) {
+      offset++;
+      whitespace();
+      while (text[offset] !== '}') {
+        const keyStart = offset;
+        stringEnd();
+        const keyEnd = offset;
+        const key = JSON.parse(text.slice(keyStart, keyEnd));
+        whitespace();
+        offset++; // colon
+        const child = value();
+        if (properties.has(key)) duplicate = true;
+        properties.set(key, { start: keyStart, end: keyEnd, value: child });
+        whitespace();
+        if (text[offset] !== ',') break;
+        offset++;
+        whitespace();
+      }
+      offset++;
+    } else if (text[offset] === '[') {
+      offset++;
+      whitespace();
+      while (text[offset] !== ']') {
+        value();
+        whitespace();
+        if (text[offset] !== ',') break;
+        offset++;
+      }
+      offset++;
+    } else if (text[offset] === '"') {
+      stringEnd();
+    } else {
+      while (offset < text.length && !/[\s,\]}]/.test(text[offset])) offset++;
+    }
+    return { start, end: offset, properties };
   }
-  const needsComma = jsonText[span.contentEnd - 1] !== ',';
-  return jsonText.slice(0, span.contentEnd) + (needsComma ? ',' : '') + '\n' + snippet + jsonText.slice(span.contentEnd);
-}
-
-function findJsonObjectSpan(jsonText, pathParts) {
-  let searchFrom = 0;
-  if (pathParts.length) {
-    const pos = findJsonKeyLocation(jsonText, pathParts.join('.'));
-    if (!pos) return undefined;
-    const colon = jsonText.indexOf(':', positionToOffset(jsonText, pos));
-    if (colon === -1) return undefined;
-    searchFrom = colon + 1;
+  const root = value();
+  return duplicate ? undefined : root;
+}
+
+function findJsonProperty(node, parts) {
+  if (!node?.properties) return undefined;
+  let found;
+  for (let count = 1; count <= parts.length; count++) {
+    const property = node.properties.get(parts.slice(0, count).join('.'));
+    if (!property) continue;
+    const candidate = count === parts.length ? property : findJsonProperty(property.value, parts.slice(count));
+    if (!candidate) continue;
+    if (found) return undefined; // dotted and nested representations collide
+    found = candidate;
   }
-  const openBrace = jsonText.indexOf('{', searchFrom);
-  if (openBrace === -1) return undefined;
-  const closeBrace = matchBrace(jsonText, openBrace);
-  if (closeBrace === -1) return undefined;
-  let contentEnd = closeBrace;
-  while (contentEnd > openBrace + 1 && /\s/.test(jsonText[contentEnd - 1])) contentEnd--;
-  return { openBrace, closeBrace, contentEnd };
+  return found;
 }
 
-function matchBrace(text, open) {
+// Insert only into an unambiguous object path. Existing scalar/array prefixes,
+// duplicate properties and existing values are never overwritten.
+export function insertNestedJsonKey(jsonText, key, value = '') {
+  let node = parseJsonStructure(jsonText);
+  let parts = key.split('.');
+  if (!node?.properties || parts.some((part) => !part)) return undefined;
   let depth = 0;
-  let quote = false;
-  let escaped = false;
-  for (let i = open; i < text.length; i++) {
-    const ch = text[i];
-    if (quote) {
-      if (escaped) escaped = false;
-      else if (ch === '\\') escaped = true;
-      else if (ch === '"') quote = false;
-      continue;
+  while (true) {
+    const matches = [];
+    for (let count = 1; count <= parts.length; count++) {
+      const property = node.properties.get(parts.slice(0, count).join('.'));
+      if (property) matches.push({ count, property });
     }
-    if (ch === '"') quote = true;
-    else if (ch === '{') depth++;
-    else if (ch === '}' && --depth === 0) return i;
+    if (!matches.length) break;
+    if (matches.length !== 1) return undefined;
+    const { count, property } = matches[0];
+    if (count === parts.length || !property.value.properties) return undefined;
+    parts = parts.slice(count);
+    node = property.value;
+    depth++;
+  }
+  const eol = jsonText.includes('\r\n') ? '\r\n' : '\n';
+  const unit = detectIndentUnit(jsonText);
+  const firstProperty = node.properties.values().next().value;
+  const lineStart = firstProperty ? jsonText.lastIndexOf('\n', firstProperty.start) + 1 : -1;
+  const existingIndent = firstProperty ? jsonText.slice(lineStart, firstProperty.start) : '';
+  const indent = firstProperty && /^[ \t]+$/.test(existingIndent) ? existingIndent : unit.repeat(depth + 1);
+  const snippet = buildNestedProperty(parts, value, indent, unit, eol);
+  let contentEnd = node.end - 1;
+  while (contentEnd > node.start + 1 && /\s/.test(jsonText[contentEnd - 1])) contentEnd--;
+  if (!node.properties.size) {
+    return jsonText.slice(0, node.start + 1) + eol + snippet + eol + indent.slice(0, -unit.length) + jsonText.slice(node.end - 1);
   }
-  return -1;
+  return jsonText.slice(0, contentEnd) + ',' + eol + snippet + jsonText.slice(contentEnd);
 }
 
 function detectIndentUnit(jsonText) {
@@ -910,19 +1078,20 @@ function detectIndentUnit(jsonText) {
   return match ? match[1] : '  ';
 }
 
-function buildNestedProperty(parts, value, indent, unit) {
+function buildNestedProperty(parts, value, indent, unit, eol) {
   const keyStr = JSON.stringify(parts[0]);
   if (parts.length === 1) return indent + keyStr + ': ' + JSON.stringify(value);
-  return indent + keyStr + ': {\n' + buildNestedProperty(parts.slice(1), value, indent + unit, unit) + '\n' + indent + '}';
+  return indent + keyStr + ': {' + eol + buildNestedProperty(parts.slice(1), value, indent + unit, unit, eol) + eol + indent + '}';
 }
 
 
+// File and directory namespaces are applied by the loader, not the parser.
 export function parseTsLocaleModule(text, fileName = 'index.ts') {
   const result = {};
   const stem = fileName.replace(/\.[cm]?[tj]sx?$/i, '');
   const exportObject = extractObjectAfter(text, /export\s+default\s*/g);
   if (exportObject) {
-    Object.assign(result, flattenJsObjectLiteral(exportObject, stem === 'index' ? '' : stem));
+    Object.assign(result, flattenJsObjectLiteral(exportObject));
   }
 
   if (stem === 'index') {

package/server/index.js

@@ -2,7 +2,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { pathToFileURL, fileURLToPath } from 'node:url';
-import { createConnection, TextDocuments, ProposedFeatures, TextDocumentSyncKind, MarkupKind, CodeActionKind } from 'vscode-languageserver/node.js';
+import { createConnection, TextDocuments, ProposedFeatures, TextDocumentSyncKind, MarkupKind, CodeActionKind, TextDocumentEdit, CreateFile, ResourceOperationKind } from 'vscode-languageserver/node.js';
 import { TextDocument } from 'vscode-languageserver-textdocument';
 import {
   flattenLocale,
@@ -39,6 +39,11 @@ const watchedLocalePaths = new Set();
 let reloadTimer;
 let configMtimeMs;
 let localeCacheByContext = new Map();
+// Whether the client can apply WorkspaceEdit.documentChanges / CreateFile.
+// Without documentChanges there is no versioned-edit support, so multi-file
+// quick fixes are not offered at all rather than applied unsafely.
+let clientSupportsDocumentChanges = false;
+let clientSupportsCreateFile = false;
 const configWatchIntervalMs = 1000;
 const localeWatchIntervalMs = 1000;
 const reloadDebounceMs = 100;
@@ -46,6 +51,11 @@ const reloadDebounceMs = 100;
 connection.onInitialize((params) => {
   workspaceRoot = params.workspaceFolders?.[0]?.uri ? fileURLToPath(params.workspaceFolders[0].uri) : (params.rootUri ? fileURLToPath(params.rootUri) : process.cwd());
   zedSettingsConfig = normalizeIncomingSettings(params.initializationOptions);
+  const editCaps = params.capabilities?.workspace?.workspaceEdit;
+  clientSupportsDocumentChanges = editCaps?.documentChanges === true;
+  clientSupportsCreateFile = clientSupportsDocumentChanges
+    && Array.isArray(editCaps?.resourceOperations)
+    && editCaps.resourceOperations.includes(ResourceOperationKind.Create);
   loadConfig();
   watchConfigFile();
   return { capabilities: { textDocumentSync: TextDocumentSyncKind.Incremental, hoverProvider: true, completionProvider: { triggerCharacters: ['.', '"', "'"] }, definitionProvider: true, referencesProvider: true, inlayHintProvider: true, codeActionProvider: true } };
@@ -59,12 +69,38 @@ connection.onInitialized(() => {
 });
 
 documents.onDidOpen((event) => {
+  if (isLocaleDocument(event.document)) {
+    // An open (possibly dirty) locale document overrides the disk copy, so a
+    // previously cached load is stale the moment the file opens.
+    invalidateLocaleCaches();
+  }
   validate(event.document);
   // A freshly started server may receive the inlay-hint request before the
   // locale cache is ready; prompt the editor to re-request once it is.
   refreshInlayHints();
 });
-documents.onDidChangeContent((event) => validate(event.document));
+
+documents.onDidChangeContent((event) => {
+  if (isLocaleDocument(event.document)) {
+    // Open locale text feeds the cache, so it must be dropped now — the very
+    // next request must already see this snapshot, not a debounced reload.
+    invalidateLocaleCaches();
+    refreshOpenDocuments();
+    refreshInlayHints();
+    return;
+  }
+  validate(event.document);
+});
+
+// An open locale document overrides the disk copy. Closing it reverts to
+// disk, which is also a content change for every feature.
+documents.onDidClose((event) => {
+  if (!isLocaleDocument(event.document)) return;
+  invalidateLocaleCaches();
+  refreshOpenDocuments();
+  refreshInlayHints();
+});
+
 documents.onDidSave(() => scheduleProjectReload());
 
 connection.onDidChangeConfiguration((params) => {
@@ -73,6 +109,7 @@ connection.onDidChangeConfiguration((params) => {
 });
 
 connection.onHover((params) => {
+  if (isLocaleFileUri(params.textDocument.uri)) return null;
   const doc = documents.get(params.textDocument.uri);
   if (!doc) return null;
   const item = keyAtPosition(doc.getText(), params.position);
@@ -86,16 +123,19 @@ connection.onHover((params) => {
 });
 
 connection.onCompletion((params) => {
-  if (!isSourceFile(params.textDocument.uri)) return [];
+  if (!isSourceFile(params.textDocument.uri) || isLocaleFileUri(params.textDocument.uri)) return [];
   const doc = documents.get(params.textDocument.uri);
+  if (!doc) return [];
+  const prefix = getCompletionPrefix(doc.getText(), params.position);
+  // undefined = caret is not inside an i18n call; '' = empty key prefix.
+  if (prefix === undefined) return [];
   const context = getProjectContext(params.textDocument.uri);
   const { locales } = loadLocalesForContext(context);
-  const prefix = doc ? getCompletionPrefix(doc.getText(), params.position) : '';
   return getCompletions(prefix, locales, context.config.defaultLocale);
 });
 
 connection.languages.inlayHint.on((params) => {
-  if (!isSourceFile(params.textDocument.uri)) return [];
+  if (!isSourceFile(params.textDocument.uri) || isLocaleFileUri(params.textDocument.uri)) return [];
   const doc = documents.get(params.textDocument.uri);
   if (!doc) return [];
   const context = getProjectContext(params.textDocument.uri);
@@ -104,18 +144,15 @@ connection.languages.inlayHint.on((params) => {
 });
 
 connection.onDefinition((params) => {
+  if (isLocaleFileUri(params.textDocument.uri)) return null;
   const doc = documents.get(params.textDocument.uri);
   if (!doc) return null;
   const item = keyAtPosition(doc.getText(), params.position);
   if (!item) return null;
   const context = getProjectContext(params.textDocument.uri);
   const { locales, localeTexts } = loadLocalesForContext(context);
-  const keyTokenLength = item.key.split('.').at(-1).length + 2;
   const locations = collectLocaleKeyTargets(locales, item.key, localeTexts, context.config.defaultLocale)
-    .map(({ filePath, position }) => ({
-      uri: pathToFileURL(filePath).toString(),
-      range: { start: position, end: { line: position.line, character: position.character + keyTokenLength } },
-    }));
+    .map(({ filePath, range }) => ({ uri: pathToFileURL(filePath).toString(), range }));
   return locations.length ? locations : null;
 });
 
@@ -128,12 +165,8 @@ connection.onReferences((params) => {
   const locations = collectCodeReferences(context, key);
   if (params.context?.includeDeclaration) {
     const { locales, localeTexts } = loadLocalesForContext(context);
-    const keyTokenLength = key.split('.').at(-1).length + 2;
-    for (const { filePath, position } of collectLocaleKeyTargets(locales, key, localeTexts, context.config.defaultLocale)) {
-      locations.push({
-        uri: pathToFileURL(filePath).toString(),
-        range: { start: position, end: { line: position.line, character: position.character + keyTokenLength } },
-      });
+    for (const { filePath, range } of collectLocaleKeyTargets(locales, key, localeTexts, context.config.defaultLocale)) {
+      locations.push({ uri: pathToFileURL(filePath).toString(), range });
     }
   }
   return locations.length ? locations : null;
@@ -143,13 +176,13 @@ connection.onCodeAction((params) => {
   const doc = documents.get(params.textDocument.uri);
   const diagnostics = params.context.diagnostics || [];
   const actions = [];
-  if (doc) {
+  if (clientSupportsDocumentChanges && doc && isSourceFile(params.textDocument.uri) && !isLocaleFileUri(params.textDocument.uri)) {
     for (const action of getParamCodeActions(doc.getText(), diagnostics)) {
       actions.push({
         title: action.title,
         kind: CodeActionKind.QuickFix,
         diagnostics: [action.diagnostic],
-        edit: { changes: { [params.textDocument.uri]: [action.edit] } },
+        edit: { documentChanges: [TextDocumentEdit.create({ uri: doc.uri, version: doc.version }, [action.edit])] },
       });
     }
   }
@@ -157,10 +190,8 @@ connection.onCodeAction((params) => {
   return actions;
 });
 
-// Quick fix for a "missing i18n key" diagnostic: create the key (empty value) in
-// every locale file that lacks it, as a cross-file workspace edit. Only single
-// flat JSON locale files are supported; nested/TS locales are skipped.
 function getCreateKeyActions(diagnostics, context) {
+  if (!clientSupportsDocumentChanges) return [];
   const { locales, localeTexts } = loadLocalesForContext(context);
   const actions = [];
   for (const diagnostic of diagnostics) {
@@ -168,42 +199,160 @@ function getCreateKeyActions(diagnostics, context) {
     const missingLocales = diagnostic.data?.missingLocales;
     if (!key || !Array.isArray(missingLocales) || missingLocales.length === 0) continue;
 
-    const changes = {};
-    for (const name of missingLocales) {
-      const filePath = flatLocaleFile(locales[name]);
-      if (!filePath) continue;
-      const text = localeTexts[filePath] ?? readFileSafe(filePath);
-      if (text === undefined) continue;
-      const newText = insertNestedJsonKey(text, key, '');
-      if (newText === undefined) continue;
-      changes[pathToFileURL(filePath).toString()] = [fullDocumentEdit(text, newText)];
+    const missing = missingLocales.filter((name) => locales[name] && !Object.hasOwn(locales[name].flat, key));
+    const plans = missing.map((name) => planKeyInsertion(key, locales[name], locales, localeTexts));
+    // Do not offer a partial repair of a multi-locale diagnostic.
+    if (!plans.length || plans.some((plan) => !plan || (plan.create && !clientSupportsCreateFile))) continue;
+    const documentChanges = [];
+    for (const plan of plans) {
+      // If a file appeared after this action was computed, fail rather than
+      // inserting into unrelated content at a stale offset.
+      if (plan.create) documentChanges.push(CreateFile.create(plan.uri));
+      documentChanges.push(TextDocumentEdit.create({ uri: plan.uri, version: plan.version }, [minimalTextEdit(plan.text, plan.newText)]));
     }
-
-    const fileCount = Object.keys(changes).length;
-    if (fileCount === 0) continue;
     actions.push({
-      title: `Create i18n key "${key}" in ${fileCount} locale file(s)`,
+      title: `Create i18n key "${key}" in ${plans.length} locale file(s)`,
       kind: CodeActionKind.QuickFix,
       diagnostics: [diagnostic],
-      edit: { changes },
+      edit: { documentChanges },
     });
   }
   return actions;
 }
 
-// A locale backed by a single flat .json file (not a nested directory locale).
-function flatLocaleFile(locale) {
-  if (!locale || !/\.json$/i.test(locale.path || '')) return undefined;
-  const files = locale.files?.length ? locale.files : [locale.path];
-  return files.length === 1 && files[0] === locale.path ? locale.path : undefined;
+// Namespace routing follows loaded file prefixes. Index-owned prefixes and
+// overlapping layouts are not guessed; ambiguous targets disable the action.
+function planKeyInsertion(key, locale, locales, localeTexts) {
+  if (!locale) return undefined;
+  if (!locale.directories?.length) {
+    const files = locale.files || [];
+    return files.length === 1 && /\.json$/i.test(files[0])
+      ? insertInto(files[0], key) : undefined;
+  }
+  if (locale.directories.length !== 1 || locale.topLevelFiles?.length) return undefined;
+  const directory = locale.directories[0];
+  const targets = filesByPrefix(locale);
+  const namespaceFiles = [...targets.keys()].filter((prefix) => prefix && key.startsWith(prefix + '.'));
+  if (namespaceFiles.length > 1 || targets.has(key)) return undefined;
+  const indexFiles = targets.get('') || [];
+  const indexFile = indexFiles.length === 1 && /\.json$/i.test(indexFiles[0]) ? indexFiles[0] : undefined;
+  let indexOwnsPrefix = false;
+  if (indexFiles.length) {
+    if (!indexFile) return undefined;
+    try {
+      const text = localeTexts[indexFile];
+      const prefix = key.split('.')[0];
+      // A whitespace-only index owns nothing; treat it like an empty object.
+      indexOwnsPrefix = Object.keys(JSON.parse(text.trim() ? text : '{}'))
+        .some((existing) => existing === prefix || existing.startsWith(prefix + '.'));
+    } catch { return undefined; }
+  }
+  if (namespaceFiles.length) {
+    if (indexOwnsPrefix) return undefined;
+    const stem = namespaceFiles[0];
+    const files = targets.get(stem);
+    return files.length === 1 && /\.json$/i.test(files[0])
+      ? insertInto(files[0], key.slice(stem.length + 1)) : undefined;
+  }
+  if (indexOwnsPrefix) return insertInto(indexFile, key);
+
+  const siblingStems = new Map();
+  for (const sibling of Object.values(locales)) {
+    if (sibling === locale || sibling.directories?.length !== 1 || sibling.topLevelFiles?.length) continue;
+    for (const [stem, files] of filesByPrefix(sibling)) {
+      if (!stem || !key.startsWith(stem + '.')) continue;
+      siblingStems.set(stem, (siblingStems.get(stem) || []).concat(files.map((file) => ({
+        file,
+        relativePath: path.relative(sibling.directories[0], file),
+      }))));
+    }
+  }
+  if (siblingStems.size > 1) return undefined;
+  if (siblingStems.size === 1) {
+    const [stem, targets] = siblingStems.entries().next().value;
+    if (targets.some(({ file }) => !/\.json$/i.test(file))) return undefined;
+    const relativePaths = new Set(targets.map(({ relativePath }) => relativePath));
+    if (relativePaths.size !== 1) return undefined;
+    const targetPath = path.join(directory, [...relativePaths][0]);
+    return fs.existsSync(path.dirname(targetPath))
+      ? insertOrCreate(targetPath, key.slice(stem.length + 1)) : undefined;
+  }
+  return indexFile ? insertInto(indexFile, key) : undefined;
+}
+
+function filesByPrefix(locale) {
+  const prefixes = new Map();
+  for (const file of locale.files || []) {
+    const prefix = locale.filePrefixes[file];
+    if (!prefixes.has(prefix)) prefixes.set(prefix, []);
+    prefixes.get(prefix).push(file);
+  }
+  return prefixes;
+}
+
+function insertInto(filePath, lookupKey) {
+  if (!lookupKey) return undefined;
+  const text = openDocumentText(filePath) ?? readFileSafe(filePath);
+  if (text === undefined) return undefined;
+  // A whitespace-only file has no JSON structure to insert into; seed it like
+  // an empty object (matching its line-ending style) so the fix still lands
+  // instead of silently disappearing.
+  const source = text.trim() ? text : (text.includes('\r\n') ? '{}\r\n' : '{}\n');
+  const newText = insertNestedJsonKey(source, lookupKey, '');
+  if (newText === undefined) return undefined;
+  return toEditPlan(filePath, text, newText, false);
+}
+
+// Prefer an in-place insert when the file exists or is open as a buffer (the
+// file may have been deleted on disk while its document stays alive); fall
+// back to a CreateFile only when there is truly nothing to edit.
+function insertOrCreate(filePath, lookupKey) {
+  if (fs.existsSync(filePath) || openDocument(filePath)) return insertInto(filePath, lookupKey);
+  return createIn(filePath, lookupKey);
+}
+
+// Create a missing namespace JSON file: only ever proposed with a CreateFile
+// operation ahead of the text edit, and only when the file truly does not
+// exist — never as a fallback guess.
+function createIn(filePath, lookupKey) {
+  if (!lookupKey || fs.existsSync(filePath) || openDocument(filePath)) return undefined;
+  const newText = insertNestedJsonKey('{}\n', lookupKey, '');
+  if (newText === undefined) return undefined;
+  return toEditPlan(filePath, '', newText, true);
+}
+
+function toEditPlan(filePath, text, newText, create) {
+  return { uri: pathToFileURL(filePath).toString(), version: documentVersion(filePath), text, newText, create };
+}
+
+// Smallest single edit turning `oldText` into `newText`: trim the shared
+// prefix/suffix instead of replacing the whole document.
+function minimalTextEdit(oldText, newText) {
+  let start = 0;
+  const maxStart = Math.min(oldText.length, newText.length);
+  while (start < maxStart && oldText[start] === newText[start]) start++;
+  let endOld = oldText.length;
+  let endNew = newText.length;
+  while (endOld > start && endNew > start && oldText[endOld - 1] === newText[endNew - 1]) { endOld--; endNew--; }
+  return { range: { start: offsetToPosition(oldText, start), end: offsetToPosition(oldText, endOld) }, newText: newText.slice(start, endNew) };
+}
+
+function offsetToPosition(text, offset) {
+  let line = 0;
+  let lineStart = 0;
+  for (let i = 0; i < offset && i < text.length; i++) {
+    if (text[i] === '\n') { line++; lineStart = i + 1; }
+  }
+  return { line, character: offset - lineStart };
 }
 
-function fullDocumentEdit(oldText, newText) {
-  const lines = oldText.split('\n');
-  const endLine = lines.length - 1;
-  return { range: { start: { line: 0, character: 0 }, end: { line: endLine, character: lines[endLine].length } }, newText };
+// Document version for an annotated TextDocumentEdit: the exact version for an
+// open document, null when the file is not open in the editor.
+function documentVersion(filePath) {
+  return openDocument(filePath)?.version ?? null;
 }
 
+
 function getProjectContext(uri) {
   loadConfigIfChanged();
   const filePath = uri ? fileURLToPath(uri) : workspaceRoot;
@@ -228,7 +377,7 @@ function watchLocalePaths() {
       .map((dir) => path.join(context.root, dir))
       .filter((dir) => fs.existsSync(dir));
     const loaded = loadLocalesForContext(context);
-    for (const watchPath of collectLocaleWatchPaths(loaded.locales, configuredDirs)) nextPaths.add(watchPath);
+    for (const watchPath of collectLocaleWatchPaths(loaded.locales, [...configuredDirs, ...loaded.watchDirectories])) nextPaths.add(watchPath);
   }
 
   for (const watchedPath of watchedLocalePaths) {
@@ -257,6 +406,10 @@ function scheduleProjectReload() {
   }, reloadDebounceMs);
 }
 
+function invalidateLocaleCaches() {
+  localeCacheByContext = new Map();
+}
+
 function refreshOpenDocuments() {
   for (const doc of documents.all()) validate(doc);
 }
@@ -274,7 +427,7 @@ function loadConfigIfChanged() {
   const nextMtimeMs = fs.existsSync(configPath) ? fs.statSync(configPath).mtimeMs : 0;
   if (configMtimeMs === nextMtimeMs) return;
   loadConfig();
-  localeCacheByContext = new Map();
+  invalidateLocaleCaches();
 }
 
 function loadConfig() {
@@ -304,7 +457,7 @@ function validate(document) {
   const { locales } = loadLocalesForContext(context);
   const templateLanguage = /\.vue$/i.test(document.uri) ? 'vue'
     : /\.html?$/i.test(document.uri) || document.languageId === 'html' ? 'html' : undefined;
-  if (isSourceFile(document.uri) || templateLanguage) {
+  if ((isSourceFile(document.uri) || templateLanguage) && !isLocaleFileUri(document.uri)) {
     const text = document.getText();
     const diagnostics = [
       ...getDiagnostics(text, locales),
@@ -313,12 +466,44 @@ function validate(document) {
     connection.sendDiagnostics({ uri: document.uri, diagnostics });
     return;
   }
-  const locale = findLocaleForFile(locales, fileURLToPath(document.uri));
+  const filePath = fileURLToPath(document.uri);
+  const locale = findLocaleForFile(locales, filePath);
   if (!locale) return;
-  connection.sendDiagnostics({ uri: document.uri, diagnostics: getLocaleParamDiagnostics(locale, fileURLToPath(document.uri), document.getText(), locales) });
+  connection.sendDiagnostics({ uri: document.uri, diagnostics: getLocaleParamDiagnostics(locale, filePath, document.getText(), locales) });
 }
+
 function isSourceFile(uri) { return /\.(vue|tsx?|jsx?)$/i.test(uri); }
 
+const LOCALE_FILE_RE = /\.(json|[cm]?[tj]s)$/i;
+
+// Is this file inside a localeDir of ANY configured context? Locale files are
+// identified before source files: a TS locale module must never get source
+// diagnostics, completions or inlay hints.
+function localeDirOfFile(filePath) {
+  const normalized = normalizeFsPathLocal(path.resolve(filePath));
+  for (const context of getAllConfiguredContexts()) {
+    const contextRoot = normalizeFsPathLocal(context.root);
+    for (const dir of context.config.localeDirs || []) {
+      const absDir = normalizeFsPathLocal(path.resolve(contextRoot, dir));
+      if (!isPathInsidePath(normalized, absDir) || normalized === absDir) continue;
+      const relative = normalized.slice(absDir.length + 1);
+      return { context, dir: absDir, relative };
+    }
+  }
+  return undefined;
+}
+
+function isLocaleFileUri(uri) {
+  let filePath;
+  try { filePath = fileURLToPath(uri); } catch { return false; }
+  const info = localeDirOfFile(filePath);
+  return !!info && LOCALE_FILE_RE.test(filePath);
+}
+
+function isLocaleDocument(document) {
+  try { return isLocaleFileUri(document.uri); } catch { return false; }
+}
+
 const IGNORED_SCAN_DIRS = new Set(['node_modules', 'dist', 'build', 'out', 'coverage', 'vendor', '.output', '.next', '.nuxt', '.cache']);
 const MAX_SCAN_FILES = 5000;
 
@@ -328,10 +513,14 @@ function resolveKeyAtPosition(uri, position, context) {
   const filePath = fileURLToPath(uri);
   const text = documents.get(uri)?.getText() ?? readFileSafe(filePath);
   if (!text) return undefined;
-  if (isSourceFile(uri)) return keyAtPosition(text, position)?.key;
   const { locales } = loadLocalesForContext(context);
   const locale = findLocaleForFile(locales, filePath);
-  return locale ? localeKeyAtPosition(locale, filePath, text, position) : undefined;
+  // Locale membership wins over the .ts source check: a caret on a key inside
+  // en.ts / zh/index.ts must resolve to the flattened key, never to source
+  // call sites (which would also spuriously match object literals).
+  if (locale) return localeKeyAtPosition(locale, filePath, text, position);
+  if (isSourceFile(uri) && !isLocaleFileUri(uri)) return keyAtPosition(text, position)?.key;
+  return undefined;
 }
 
 function findLocaleForFile(locales, filePath) {
@@ -343,29 +532,57 @@ function findLocaleForFile(locales, filePath) {
   return undefined;
 }
 
-// Every source-code usage of `key` within the project/package root. Prefers the
-// in-memory text of open (possibly unsaved) documents over the on-disk copy.
+// Every source-code usage of `key` inside this context only: files under the
+// context root, excluding roots of other configured packages and locale
+// directories, plus open (possibly unsaved) source documents belonging to the
+// context that do not exist on disk yet. Open text wins over disk text.
 function collectCodeReferences(context, key) {
-  const openTextByPath = new Map();
-  for (const doc of documents.all()) {
-    try { openTextByPath.set(path.resolve(fileURLToPath(doc.uri)), doc.getText()); } catch { /* non-file uri */ }
-  }
+  const contextRoot = normalizeFsPathLocal(context.root);
+  const nestedRoots = getAllConfiguredContexts()
+    .map((candidate) => normalizeFsPathLocal(candidate.root))
+    .filter((root) => root !== contextRoot && isPathInsidePath(root, contextRoot));
+
   const locations = [];
-  for (const filePath of collectSourceFiles(context.root)) {
-    const text = openTextByPath.get(path.resolve(filePath)) ?? readFileSafe(filePath);
-    if (!text) continue;
+  const scanned = new Set();
+  const scan = (filePath, text, uri) => {
+    const resolved = normalizeFsPathLocal(path.resolve(filePath));
+    if (scanned.has(resolved)) return;
+    scanned.add(resolved);
+    if (text === undefined) return;
     for (const range of findCodeKeyRanges(text, key)) {
-      locations.push({ uri: pathToFileURL(filePath).toString(), range });
+      locations.push({ uri: uri ?? pathToFileURL(filePath).toString(), range });
     }
+  };
+
+  for (const filePath of collectSourceFiles(context.root, nestedRoots)) {
+    scan(filePath, openDocumentText(filePath) ?? readFileSafe(filePath));
+  }
+
+  for (const doc of documents.all()) {
+    let filePath;
+    try { filePath = fileURLToPath(doc.uri); } catch { continue; }
+    if (!isSourceFile(filePath)) continue;
+    const resolved = normalizeFsPathLocal(path.resolve(filePath));
+    if (!isPathInsidePath(resolved, contextRoot)) continue;
+    if (nestedRoots.some((root) => isPathInsidePath(resolved, root))) continue;
+    if (isLocaleFileUri(doc.uri)) continue;
+    scan(filePath, doc.getText(), doc.uri);
   }
   return locations;
 }
 
-function collectSourceFiles(root) {
+function collectSourceFiles(root, excludedRoots = []) {
   const files = [];
   const stack = [root];
+  const excluded = excludedRoots.map((entry) => normalizeFsPathLocal(entry));
+  const localeDirs = getAllConfiguredContexts()
+    .flatMap((context) => (context.config.localeDirs || [])
+      .map((dir) => normalizeFsPathLocal(path.resolve(context.root, dir))));
   while (stack.length && files.length < MAX_SCAN_FILES) {
     const dir = stack.pop();
+    const normalizedDir = normalizeFsPathLocal(dir);
+    if (excluded.some((entry) => isPathInsidePath(normalizedDir, entry))) continue;
+    if (localeDirs.some((entry) => normalizedDir === entry || normalizedDir.startsWith(entry + '/'))) continue;
     let entries;
     try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { continue; }
     for (const entry of entries) {
@@ -381,10 +598,39 @@ function collectSourceFiles(root) {
   return files;
 }
 
+function openDocument(filePath) {
+  let target;
+  try { target = path.resolve(filePath); } catch { return undefined; }
+  for (const doc of documents.all()) {
+    try {
+      if (path.resolve(fileURLToPath(doc.uri)) === target) return doc;
+    } catch { /* non-file uri */ }
+  }
+  return undefined;
+}
+
+// In-memory text of an open (possibly unsaved) document for filePath.
+function openDocumentText(filePath) {
+  return openDocument(filePath)?.getText();
+}
+
 function readFileSafe(filePath) {
   try { return fs.readFileSync(filePath, 'utf8'); } catch { return undefined; }
 }
 
+// Prefer the open document's current text; fall back to disk.
+function localeText(filePath) {
+  return openDocumentText(filePath) ?? readFileSafe(filePath);
+}
+
+function normalizeFsPathLocal(value) {
+  return String(value || '').replace(/\\/g, '/').replace(/\/+$/g, '');
+}
+
+function isPathInsidePath(filePath, root) {
+  return filePath === root || filePath.startsWith(root + '/');
+}
+
 function getAllConfiguredContexts() {
   loadConfigIfChanged();
   return [resolveProjectContext(workspaceRoot, workspaceRoot, config), ...config.packages.map((pkg) => ({
@@ -404,54 +650,104 @@ function loadLocalesForContext(context) {
 
   const locales = {};
   const localeTexts = {};
-  for (const dir of context.config.localeDirs) {
-    const fullDir = path.join(context.root, dir);
+  const watchDirectories = new Set();
+  const localeRoots = context.config.localeDirs.map((dir) => path.resolve(context.root, dir));
+  for (const fullDir of localeRoots) {
     if (!fs.existsSync(fullDir)) continue;
     loadLocaleFiles(fullDir, locales, localeTexts);
     for (const entry of fs.readdirSync(fullDir, { withFileTypes: true })) {
-      if (entry.isDirectory()) loadLocaleDirectory(path.join(fullDir, entry.name), entry.name, locales, localeTexts);
+      if (entry.isDirectory()) loadLocaleDirectory(path.join(fullDir, entry.name), entry.name, locales, localeTexts, localeRoots, watchDirectories);
     }
   }
-  const loaded = { locales, localeTexts };
+  const loaded = { locales, localeTexts, watchDirectories: [...watchDirectories] };
   localeCacheByContext.set(cacheKey, loaded);
   return loaded;
 }
 
-function loadLocaleDirectory(localeDir, localeName, next, localeTexts) {
-  next[localeName] ||= { path: localeDir, flat: {}, files: [] };
-  for (const file of fs.readdirSync(localeDir)) {
+function loadLocaleDirectory(localeDir, localeName, next, localeTexts, localeRoots, watchDirectories, rootDir = localeDir) {
+  // An explicit locale root owns its subtree, independently of config order.
+  if (localeRoots.includes(localeDir)) return;
+  // Fileless directories still need watching, but must not create phantom locales.
+  watchDirectories.add(localeDir);
+  for (const entry of fs.readdirSync(localeDir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    const file = entry.name;
     const fullPath = path.join(localeDir, file);
-    if (fs.statSync(fullPath).isDirectory()) continue;
+    if (entry.isDirectory()) {
+      loadLocaleDirectory(fullPath, localeName, next, localeTexts, localeRoots, watchDirectories, rootDir);
+      continue;
+    }
+    if (!LOCALE_FILE_RE.test(file)) continue;
+    if (entry.isSymbolicLink() && fs.statSync(fullPath).isDirectory()) continue;
+    next[localeName] ||= { path: rootDir, flat: {}, keyFiles: {}, files: [] };
+    const locale = next[localeName];
+    locale.directories ||= [];
+    if (!locale.directories.includes(rootDir)) locale.directories.push(rootDir);
+    locale.filePrefixes ||= {};
+    const relativeFile = path.relative(rootDir, fullPath);
+    if (!locale.files.includes(fullPath)) locale.files.push(fullPath);
+    locale.filePrefixes[fullPath] = localeFilePrefix(relativeFile);
     try {
-      const text = fs.readFileSync(fullPath, 'utf8');
-      if (file.endsWith('.json')) Object.assign(next[localeName].flat, prefixByFile(file, flattenLocale(JSON.parse(text))));
-      else if (/\.[cm]?[tj]s$/i.test(file)) Object.assign(next[localeName].flat, parseTsLocaleModule(text, file));
-      else continue;
-      next[localeName].files.push(fullPath);
+      const text = localeText(fullPath);
+      if (text === undefined) continue;
       localeTexts[fullPath] = text;
+      const flat = prefixByFile(relativeFile, file.endsWith('.json')
+        ? flattenLocale(JSON.parse(text)) : parseTsLocaleModule(text, file));
+      for (const [key, value] of Object.entries(flat)) {
+        locale.flat[key] = value;
+        locale.keyFiles[key] = fullPath;
+      }
     } catch (error) { connection.console.warn('Failed to load locale file ' + fullPath + ': ' + error.message); }
   }
 }
 
+// Top-level locale files named after the locale itself (en.json, en.ts, …).
+// Keys are stored verbatim — unlike directory locales no file-stem prefix is
+// applied, so parseTsLocaleModule runs as an 'index' module. When both a .json
+// and a .ts/.js file share the locale name, their keys merge (sorted read
+// order keeps this deterministic); writing stays a JSON-only feature.
 function loadLocaleFiles(fullDir, next, localeTexts) {
-  for (const file of fs.readdirSync(fullDir)) {
+  const files = fs.readdirSync(fullDir).sort((a, b) => {
+    const aJson = a.endsWith('.json') ? 0 : 1;
+    const bJson = b.endsWith('.json') ? 0 : 1;
+    return aJson - bJson || a.localeCompare(b);
+  });
+  for (const file of files) {
     const fullPath = path.join(fullDir, file);
     if (fs.statSync(fullPath).isDirectory()) continue;
     try {
-      const text = fs.readFileSync(fullPath, 'utf8');
-      if (file.endsWith('.json')) {
-        const name = path.basename(file, '.json');
-        next[name] = { path: fullPath, flat: flattenLocale(JSON.parse(text)), files: [fullPath] };
-        localeTexts[fullPath] = text;
+      const isJson = file.endsWith('.json');
+      const isModule = /\.[cm]?[tj]s$/i.test(file);
+      if (!isJson && !isModule) continue;
+      const name = file.replace(/\.(json|[cm]?[tj]s)$/i, '');
+      next[name] ||= { path: fullPath, flat: {}, keyFiles: {}, files: [], topLevelFiles: [] };
+      next[name].filePrefixes ||= {};
+      next[name].filePrefixes[fullPath] = '';
+      next[name].topLevelFiles ||= [];
+      if (!next[name].files.includes(fullPath)) next[name].files.push(fullPath);
+      if (!next[name].topLevelFiles.includes(fullPath)) next[name].topLevelFiles.push(fullPath);
+      const text = localeText(fullPath);
+      if (text === undefined) continue;
+      localeTexts[fullPath] = text;
+      const flat = isJson ? flattenLocale(JSON.parse(text)) : parseTsLocaleModule(text, 'index.ts');
+      for (const [key, value] of Object.entries(flat)) {
+        next[name].flat[key] = value;
+        next[name].keyFiles[key] = fullPath;
       }
     } catch (error) { connection.console.warn('Failed to load locale file ' + fullPath + ': ' + error.message); }
   }
 }
 
 function prefixByFile(file, flat) {
-  const stem = path.basename(file, path.extname(file));
-  if (stem === 'index') return flat;
-  return Object.fromEntries(Object.entries(flat).map(([key, value]) => [stem + '.' + key, value]));
+  const prefix = localeFilePrefix(file);
+  if (!prefix) return flat;
+  return Object.fromEntries(Object.entries(flat).map(([key, value]) => [prefix + '.' + key, value]));
+}
+
+function localeFilePrefix(file) {
+  const segments = file.replace(/\\/g, '/').split('/');
+  const stem = segments.pop().replace(/\.[^.]+$/, '');
+  if (stem !== 'index') segments.push(stem);
+  return segments.join('.');
 }
 
 documents.listen(connection);