@lingfan-engine/editor 0.0.0-stage → 0.1.0

package/src/i18n/reconcile.ts

@@ -0,0 +1,71 @@
+/**
+ * i18n 工具链 · 缺译 / 多译对账。
+ *
+ * 对账 = 原文键集合与各语言 overlay 键集合的双向差：
+ * - **缺译**（正向）= 原文 − 该语言 overlay（按语言分组；运行期「缺译文回退原文」的预警）
+ * - **多译**（反向）= overlay 键 − 原文（与诊断 `unused-translation` 同口径：未使用 = 冗余）
+ *
+ * 纯函数 + 可读报告文本（编辑器面板一节 / CLI stdout 共用）。加密 overlay（`.json.enc`）
+ * 走同一解密供给后与明文同口径参与（供给侧职责见 adapters `loadDiagnosticSupply`）。
+ */
+
+import type { EditorTexts } from "../contracts/index.ts";
+import { resolveEditorTexts } from "../contracts/index.ts";
+
+export interface TranslationReconcileReport {
+  /** 每语言缺译键（稳定排序；语言无缺译时为空数组——「齐」也是显式状态） */
+  missingByLang: ReadonlyMap<string, readonly string[]>;
+  /** 多译键（跨语言并集口径，稳定排序；= unused-translation 诊断同源） */
+  unused: readonly string[];
+}
+
+/**
+ * 三态对账：某语言缺译 / 多译 / 齐。`overlayKeysByLang` 的键 = 语言码
+ * （单语言工具传单键对象即可）。
+ */
+export function reconcileTranslations(
+  sources: readonly string[],
+  overlayKeysByLang: Readonly<Record<string, readonly string[]>>,
+): TranslationReconcileReport {
+  const sourceSet = new Set(sources);
+  const missingByLang = new Map<string, readonly string[]>();
+  const unused = new Set<string>();
+  for (const [lang, keys] of Object.entries(overlayKeysByLang)) {
+    const keySet = new Set(keys);
+    for (const key of keySet) {
+      if (!sourceSet.has(key)) unused.add(key);
+    }
+    const missing: string[] = [];
+    for (const source of sourceSet) {
+      if (!keySet.has(source)) missing.push(source);
+    }
+    missing.sort();
+    missingByLang.set(lang, missing);
+  }
+  return { missingByLang, unused: [...unused].sort() };
+}
+
+/** 可读报告（编辑器面板一节 / CLI stdout 共用）；逐语言缺译 + 多译两节。
+ * `texts`（可选）= 集中文案表注入（缺省 defaultEditorTexts）。 */
+export function formatTranslationReport(
+  report: TranslationReconcileReport,
+  texts: Partial<EditorTexts> = {},
+): string {
+  const t = resolveEditorTexts(texts);
+  const lines: string[] = [];
+  for (const [lang, missing] of [...report.missingByLang.entries()].sort()) {
+    if (missing.length === 0) {
+      lines.push(t.missingZero(lang));
+      continue;
+    }
+    lines.push(t.missingCount(lang, missing.length));
+    for (const key of missing) lines.push(`  - ${key}`);
+  }
+  if (report.unused.length === 0) {
+    lines.push(t.unusedZero());
+  } else {
+    lines.push(t.unusedCount(report.unused.length));
+    for (const key of report.unused) lines.push(`  - ${key}`);
+  }
+  return lines.join("\n");
+}

package/src/i18n/skeleton.ts

@@ -0,0 +1,112 @@
+/**
+ * i18n 工具链 · overlay 骨架生成。
+ *
+ * 给定语言与分组策略，产出**文件内容**（原文 → 既有译文或占位）；落盘归调用方
+ * （编辑器保存 / CLI），本模块保持纯函数（不碰平台 API）。合并语义与运行期
+ * `mergeOverlayFiles` 对齐（main.json 兜底 + 其余按供给序覆盖）⇒ 骨架喂回合并后
+ * 键集合与 `extractStoryKeys` 输出**双向一致**（互锁测试锁定）。
+ *
+ * 布局覆盖 overlay 形态：「平铺」= 条目即键值平面（三形态共用）；
+ * 单大文件 `Lang/{lang}.json`、目录 `Lang/{lang}/main.json`、按故事分类
+ * `Lang/{lang}/{章节子目录}/{故事}.json`——**per-story 镜像 `Stories/` 的递归目录**
+ * （章节子目录更好区分归类；`.json` / `.json.enc`
+ * 双识别归运行期供给，骨架产明文）。**增量模式**：命中的既有译文原样保留（含空串
+ * 译文——运行期「命中即用」语义），绝不覆盖。
+ */
+
+import type { EditorTexts } from "../contracts/index.ts";
+import { resolveEditorTexts } from "../contracts/index.ts";
+import { isSafeFileNameSegment } from "@lingfan-engine/core";
+
+/** 占位策略：original = 原文占位（未翻译时画面可读，翻译工作表语义）；empty = 空串（运行期命中即隐句） */
+export type SkeletonPlaceholder = "original" | "empty";
+
+/** 骨架布局：single = `Lang/{lang}.json`；main = `Lang/{lang}/main.json`；per-story = 镜像 Stories/ 递归目录 */
+export type SkeletonLayout = "single" | "main" | "per-story";
+
+export interface OverlaySkeletonFile {
+  /** 相对资源根的 overlay 路径 */
+  path: string;
+  /** 键值平面（键 = 原文，稳定排序；值 = 既有译文（增量保留）或占位） */
+  entries: Record<string, string>;
+  /** 序列化好的文件内容（2 空格缩进 + 结尾换行；落盘即用，同输入逐字节确定） */
+  content: string;
+}
+
+/** overlay 根目录名（与运行期 Lang/ 供给面同源；单一出处供路径模板与测试共用） */
+export const LANG_DIR = "Lang";
+
+export interface SkeletonOptions {
+  lang: string;
+  layout: SkeletonLayout;
+  /**
+   * 故事 → 该故事的原文键（`extractStoryKeys` 输出；键序不要求，产出内会排序）。
+   * **键 = 故事文件相对 `Stories/` 的路径（不含扩展名）**，如 `chapter1/tavern`——
+   * per-story 布局按它镜像 `Stories/` 递归目录（平铺工程的键 = 故事 id，语义一致）。
+   */
+  storyKeys: ReadonlyMap<string, readonly string[]>;
+  /** 增量模式：该语言已存在的 overlay（路径 → 条目）；命中的键保留原值 */
+  existing?: ReadonlyMap<string, Record<string, string>>;
+  placeholder?: SkeletonPlaceholder;
+  /** 集中文案表注入（缺省 defaultEditorTexts） */
+  texts?: Partial<EditorTexts>;
+}
+
+/**
+ * 产出骨架文件列表。fail-closed：`lang` / 故事 id 不合法即抛——骨架路径要能落进
+ * `Lang/` 而不越界（与故事文件名同一安全口径 `isSafeFileNameSegment`）。
+ */
+export function planOverlaySkeleton(
+  options: SkeletonOptions,
+): OverlaySkeletonFile[] {
+  const {
+    lang,
+    layout,
+    storyKeys,
+    existing,
+    placeholder = "original",
+  } = options;
+  const t: EditorTexts = resolveEditorTexts(options.texts);
+  if (typeof lang !== "string" || !isSafeFileNameSegment(lang)) {
+    throw new Error(t.invalidLangCode(String(lang)));
+  }
+  const build = (
+    path: string,
+    keys: readonly string[],
+  ): OverlaySkeletonFile => {
+    const prior = existing?.get(path) ?? {};
+    const entries: Record<string, string> = {};
+    for (const key of [...keys].sort()) {
+      // 既有条目原样保留（含空串译文）；`undefined` = 未命中 → 占位
+      const kept = prior[key];
+      entries[key] =
+        typeof kept === "string" ? kept : placeholder === "empty" ? "" : key;
+    }
+    return { path, entries, content: `${JSON.stringify(entries, null, 2)}\n` };
+  };
+  if (layout === "single" || layout === "main") {
+    const union = new Set<string>();
+    for (const keys of storyKeys.values()) {
+      for (const key of keys) union.add(key);
+    }
+    const path =
+      layout === "single"
+        ? `${LANG_DIR}/${lang}.json`
+        : `${LANG_DIR}/${lang}/main.json`;
+    return [build(path, [...union])];
+  }
+  // per-story：镜像 `Stories/` 的递归目录——
+  // 键 = 故事相对 `Stories/` 的路径（不含扩展名）；**段级**安全校验防路径越界。
+  const files: OverlaySkeletonFile[] = [];
+  for (const [storyPath, keys] of storyKeys) {
+    const segments = storyPath.split("/");
+    if (
+      storyPath === "" ||
+      segments.some((segment) => !isSafeFileNameSegment(segment))
+    ) {
+      throw new Error(t.invalidStoryPath(storyPath));
+    }
+    files.push(build(`${LANG_DIR}/${lang}/${storyPath}.json`, keys));
+  }
+  return files;
+}

package/src/i18n/storyKeys.ts

@@ -0,0 +1,27 @@
+import { STORIES_DIR } from "@lingfan-engine/core";
+
+/**
+ * 列 → 产物故事键（i18n per-story 骨架的权威口径）：列落盘文件相对 `Stories/` 的
+ * 路径、不含扩展名——与 `planOverlaySkeleton` 的 per-story 键、构建的写盘路径
+ * （`Stories/<相对源路径>.json`，文件名与列 id 解耦）同一规则，保证骨架
+ * `Lang/{lang}/{故事键}.json` 与 `Resources/Stories/` 递归目录严格镜像。
+ *
+ * 多目录形态下列 id ≠ 文件名，键必须从 `column.sourcePath`（构建回填的产物路径）
+ * 推导；缺省/非法（非 `Stories/` 前缀、含 `..`）回退引擎默认布局 `Stories/{id}.json`。
+ */
+export function columnStoryKey(column: {
+  readonly id: string;
+  readonly sourcePath?: string;
+}): string {
+  const fallback = `${STORIES_DIR}/${column.id}.json`;
+  const sourcePath = column.sourcePath;
+  const resolved =
+    typeof sourcePath === "string" &&
+    sourcePath.startsWith(`${STORIES_DIR}/`) &&
+    !sourcePath.includes("..")
+      ? sourcePath
+      : fallback;
+  const relative = resolved.slice(STORIES_DIR.length + 1);
+  const dot = relative.lastIndexOf(".");
+  return dot > 0 ? relative.slice(0, dot) : relative;
+}

package/src/i18n/surfaces.ts

@@ -0,0 +1,54 @@
+/**
+ * i18n 工具链 · 翻译面单一事实源。
+ *
+ * `TRANSLATE_SURFACES` 声明「命令流上哪些 op 的哪些字段会被运行期 Translate」——
+ * 诊断的原文收集（`indexStory.originals`）与键抽取器（`extractStoryKeys`）**共同消费本表**，
+ * 新增翻译面只改这一处（两侧自动同口径）。元素展示文字（`text`）不在命令流上，
+ * 不走此表——由两侧各自的元素遍历单独入集（与运行期 `translateElements` 对齐）。
+ *
+ * 路径语法：`a.b` 逐段取值；`a[].b` 的 `[]` = 对数组逐项迭代（`options[].text`）。
+ */
+
+/** 可翻译原文面（运行期 Translate 挂接：say 文本+说话人 / menu prompt+选项 / input prompt / notify 文本。character.screen 见下——仅入编辑器比对面，运行期不翻） */
+export const TRANSLATE_SURFACES: Readonly<Record<string, readonly string[]>> = {
+  say: ["text", "speaker"],
+  menu: ["prompt", "options[].text"],
+  input: ["prompt"],
+  notify: ["text"],
+  // character.screen 仅入编辑器比对面（原文收集/键抽取），运行期**不翻**：引擎恰好 7 个
+  // translate 调用点（runtime/i18n/translate.ts:31、ops/dialog.ts:92/107/171/175、
+  // ops/interaction.ts:42、ops/media.ts:262），均不含 screen（说话人显示名解析产物
+  // 走 say 的 Translate 挂接，查表见 runtime/ops/dialog.ts execSay；docs concepts/i18n.md 同口径）。
+  character: ["screen"],
+};
+
+/** 字段路径取值（`a[].b` = 逐项迭代；返回值与其相对指针） */
+export function valuesAtPath(
+  cmd: Record<string, unknown>,
+  path: string,
+): { value: unknown; pointer: string }[] {
+  let current: { value: unknown; pointer: string }[] = [
+    { value: cmd, pointer: "" },
+  ];
+  for (const segment of path.split(".")) {
+    const iterate = segment.endsWith("[]");
+    const key = iterate ? segment.slice(0, -2) : segment;
+    const next: { value: unknown; pointer: string }[] = [];
+    for (const entry of current) {
+      if (entry.value === null || typeof entry.value !== "object") continue;
+      const child = (entry.value as Record<string, unknown>)[key];
+      const childPointer = `${entry.pointer}/${key}`;
+      if (iterate) {
+        if (Array.isArray(child)) {
+          child.forEach((item, index) => {
+            next.push({ value: item, pointer: `${childPointer}/${index}` });
+          });
+        }
+      } else {
+        next.push({ value: child, pointer: childPointer });
+      }
+    }
+    current = next;
+  }
+  return current;
+}

package/src/i18n/table.ts

@@ -0,0 +1,235 @@
+/**
+ * i18n 工具链 · **译文表行编辑判据**（纯函数，可测）。
+ *
+ * 存在理由：译者需要「这一行不要了」「补一个键」能在**视图里就地做**，而视图不该持有判据。
+ * 本模块是那层判据的**唯一出处**，`LangView` 只负责渲染与收集意图。
+ *
+ * 三条约束：
+ *
+ * 1. **写回按语义，不按字节**：产出**规范形**（键按码元序排序 + 2 空格缩进 + 结尾换行），
+ *    与 `planOverlaySkeleton` 的 `content` 同形 ⇒ 同一输入逐字节确定，不因行序抖动而全文件重写。
+ * 2. **不丢作者意图**：译文值按 `unknown` **原样往返**（不把非字符串 coerce 成 `""`）。
+ *    coerce 看似无害，实则**保存一次就把数字/嵌套值抹平**——静默改数据。
+ * 3. **fail-closed**：空键 / 重复键 / 改键到已存在 / 删不存在的键 ⇒ 显式报错，
+ *    绝不「静默忽略」或「静默覆盖」（覆盖 = 丢译文）。
+ */
+
+import type { EditorTexts } from "../contracts/index.ts";
+import { resolveEditorTexts } from "../contracts/index.ts";
+
+/** 译文表的一行（`value` 原样保留，仅 `text` 供输入框显示） */
+export interface TranslationRow {
+  readonly key: string;
+  /** **原样往返**的值（不 coerce；写回时按此序列化） */
+  readonly value: unknown;
+  /** 给输入框的字符串形态（非字符串值的直读形态；`undefined` → 空串） */
+  readonly text: string;
+}
+
+/** 解析结果（坏 JSON / 非对象根 ⇒ `fail-closed`，不静默当空表） */
+export type TableParse =
+  | { readonly ok: true; readonly rows: readonly TranslationRow[] }
+  | { readonly ok: false; readonly error: string };
+
+/** 键按码元序比较（与既有 `LangView` 排序口径一致，不引入 locale 依赖） */
+function byKey(a: TranslationRow, b: TranslationRow): number {
+  return a.key < b.key ? -1 : a.key > b.key ? 1 : 0;
+}
+
+/** 把 `unknown` 值转成输入框可显示的文本（`null`/对象/数组给 JSON 形态，不给 `[object Object]`） */
+function displayTextOf(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (value === undefined) return "";
+  if (
+    value === null ||
+    typeof value === "number" ||
+    typeof value === "boolean"
+  ) {
+    return String(value);
+  }
+  try {
+    return JSON.stringify(value) ?? "";
+  } catch {
+    // 循环引用等不可序列化形态：如实显示占位，不提供编辑
+    return "";
+  }
+}
+
+/**
+ * 解析译文表 JSON 文本。
+ *
+ * **不接受数组根**（译文表契约是「键 → 译文」的平面对象）；数组根会被
+ * `Array.isArray` 拦住并报错。
+ * `texts`（可选）= 集中文案表注入（缺省 defaultEditorTexts）。
+ */
+export function parseTranslationTable(
+  source: string,
+  texts: Partial<EditorTexts> = {},
+): TableParse {
+  const t = resolveEditorTexts(texts);
+  let value: unknown;
+  try {
+    value = JSON.parse(source);
+  } catch (e) {
+    return { ok: false, error: t.invalidJson(String(e)) };
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return { ok: false, error: t.tableRootMustBeObject() };
+  }
+  const rows = Object.entries(value as Record<string, unknown>).map(
+    ([key, v]) => ({
+      key,
+      value: v,
+      text: displayTextOf(v),
+    }),
+  );
+  rows.sort(byKey);
+  return { ok: true, rows };
+}
+
+/** 序列化回规范形（**键按码元序** + 2 空格缩进 + 结尾换行；值原样往返） */
+export function serializeTranslationTable(
+  rows: readonly TranslationRow[],
+): string {
+  const out: Record<string, unknown> = {};
+  for (const row of [...rows].sort(byKey)) out[row.key] = row.value;
+  return `${JSON.stringify(out, null, 2)}\n`;
+}
+
+/** 变更结果（失败带**可展示给用户**的原因，成功带新行集） */
+export type TableEdit =
+  | { readonly ok: true; readonly rows: readonly TranslationRow[] }
+  | { readonly ok: false; readonly error: string };
+
+/** 空键判据（空白串、首尾空白、含控制字符一律拒绝——键要能当 JSON 键与运行期查表） */
+function keyProblem(key: string, t: EditorTexts): string | undefined {
+  if (key === "") return t.keyEmpty();
+  if (key !== key.trim()) return t.keySurroundingWhitespace();
+  if (/[\u0000-\u001f]/.test(key)) return t.keyControlChars();
+  return undefined;
+}
+
+/**
+ * 增行。
+ *
+ /** **重复键显式拒绝**（不覆盖）：译文表里一个键只能有一条，静默覆盖 = 丢译文。
+ * 新行的值恒为 `""`（未翻译）——`text` 与 `value` 同步，避免「显示空、写出 undefined」。
+ * `texts`（可选）= 集中文案表注入（缺省 defaultEditorTexts）。
+ */
+export function addTranslationRow(
+  rows: readonly TranslationRow[],
+  key: string,
+  texts: Partial<EditorTexts> = {},
+): TableEdit {
+  const t = resolveEditorTexts(texts);
+  const problem = keyProblem(key, t);
+  if (problem !== undefined) return { ok: false, error: problem };
+  if (rows.some((r) => r.key === key)) {
+    return { ok: false, error: t.keyAlreadyExists(key) };
+  }
+  return {
+    ok: true,
+    rows: [...rows, { key, value: "", text: "" }].sort(byKey),
+  };
+}
+
+/** 删行（键不存在 ⇒ 显式失败，不静默noop——上层据此提示「状态已变」） */
+export function removeTranslationRow(
+  rows: readonly TranslationRow[],
+  key: string,
+  texts: Partial<EditorTexts> = {},
+): TableEdit {
+  const t = resolveEditorTexts(texts);
+  if (!rows.some((r) => r.key === key)) {
+    return { ok: false, error: t.keyNotInTable(key) };
+  }
+  return { ok: true, rows: rows.filter((r) => r.key !== key) };
+}
+
+/** 改键（重命名）；目标已存在 ⇒ 拒绝（合并两行译文 = 静默丢数据） */
+export function renameTranslationRow(
+  rows: readonly TranslationRow[],
+  from: string,
+  to: string,
+  texts: Partial<EditorTexts> = {},
+): TableEdit {
+  const t = resolveEditorTexts(texts);
+  if (!rows.some((r) => r.key === from)) {
+    return { ok: false, error: t.keyNotInTable(from) };
+  }
+  const problem = keyProblem(to, t);
+  if (problem !== undefined) return { ok: false, error: problem };
+  if (from === to) return { ok: true, rows };
+  if (rows.some((r) => r.key === to)) {
+    return { ok: false, error: t.renameConflict(to) };
+  }
+  return {
+    ok: true,
+    rows: rows.map((r) => (r.key === from ? { ...r, key: to } : r)).sort(byKey),
+  };
+}
+
+/**
+ * 改值。
+ *
+ * **保持值的原始类型**：文本非空且原值是合法 JSON 字面量（数字/布尔/null/数组/对象）
+ * 时按该类型写回——否则「译文其实想写数字」会被引号包成字符串。但**普通文本一律按字符串**
+ *（译者打的 `123` 若原值是字符串，语义是文本 `123`；类型跟随**原值**，不跟随输入形态）。
+ * 原值非字符串时按 JSON 解析输入，失败则回落字符串（不吞错：解析失败仍写字符串原文）。
+ * `texts`（可选）= 集中文案表注入（缺省 defaultEditorTexts）。
+ */
+export function setTranslationValue(
+  rows: readonly TranslationRow[],
+  key: string,
+  text: string,
+  texts: Partial<EditorTexts> = {},
+): TableEdit {
+  const t = resolveEditorTexts(texts);
+  if (!rows.some((r) => r.key === key)) {
+    return { ok: false, error: t.keyNotInTable(key) };
+  }
+  return {
+    ok: true,
+    rows: rows.map((r) =>
+      r.key === key ? { ...r, value: coerceLike(r.value, text), text } : r,
+    ),
+  };
+}
+
+/** 值类型跟随**原值**：原值非字符串时，把输入按 JSON 解析（失败回落字符串原文） */
+function coerceLike(original: unknown, text: string): unknown {
+  if (typeof original === "string") return text;
+  if (text === "") return "";
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return text;
+  }
+}
+
+/** 脏判定（**逐行比键与值**；行数不同即脏。新增/删除/改键都必须能判出脏） */
+export function isTableDirty(
+  rows: readonly TranslationRow[],
+  base: readonly TranslationRow[],
+): boolean {
+  if (rows.length !== base.length) return true;
+  const baseByKey = new Map(base.map((r) => [r.key, r.value]));
+  for (const row of rows) {
+    if (!baseByKey.has(row.key)) return true;
+    if (!sameValue(baseByKey.get(row.key), row.value)) return true;
+  }
+  return false;
+}
+
+/** 值相等判定（**结构相等**，不用 `===`——否则对象/数组永远判脏） */
+function sameValue(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (typeof a !== typeof b) return false;
+  if (a === null || b === null) return false;
+  if (typeof a !== "object") return false;
+  try {
+    return JSON.stringify(a) === JSON.stringify(b);
+  } catch {
+    return false; // 不可序列化 ⇒ 保守判脏
+  }
+}