@arronqzy/i18n 0.1.14 → 0.1.16

package/README.md

@@ -1,6 +1,8 @@
 # @arronqzy/i18n
 
-Abuilder 共享国际化包，默认支持 **zh-CN** / **en-US**，可同时用于 React 与 Vue。
+Abuilder 的中英文案，React 和 Vue 共用同一套 key。默认 `zh-CN`，也可切到 `en-US`。
+
+编辑器里的「设置 → 语言」写的是 `localStorage` key `abuilder.locale`。面板、物料名、蓝图节点、配置提示都走这里，不要在视图包里再写一份硬编码中文。
 
 ## 安装
 
@@ -8,6 +10,8 @@ Abuilder 共享国际化包，默认支持 **zh-CN** / **en-US**，可同时用
 pnpm add @arronqzy/i18n
 ```
 
+React 和 Vue 都是 optional peer。只用一端时不必装另一端。
+
 ## React
 
 ```tsx
@@ -21,22 +25,40 @@ const { t, locale, setLocale } = useI18n();
 t("panel.menubar.file");
 ```
 
+`useI18n()` 必须在 **同一份包实例** 的 `I18nProvider` 下面。Umi / pnpm 有时会打出两份 `@arronqzy/i18n`，面板的 Provider 和蓝图的 hook 对不上，就会报 `useI18n must be used within I18nProvider`。
+
+处理方式：
+
+- 库代码用 `useI18nOptional()`：没有 Provider 时回退中文，不抛错。
+- 入口用 `EnsureI18nProvider`：本包实例上方没有 Provider 时自己包一层。
+- 宿主用 `overrides` / `resolutions` 把 `@arronqzy/i18n` 收成一份，语言切换才能两端同步。
+
+```tsx
+import { EnsureI18nProvider, useI18nOptional } from "@arronqzy/i18n/react";
+```
+
 ## Vue
 
 ```ts
 import { abuilderI18n, useI18n, provideI18n } from "@arronqzy/i18n/vue";
 
 app.use(abuilderI18n, { locale: "en-US" });
-// 或在组件内 provideI18n({ locale: "zh-CN" })
+// 或在 setup 里 provideI18n({ locale: "zh-CN" })
+
+const { t, locale, setLocale } = useI18n();
 ```
 
-## 语言解析优先级
+没有 `provide` 时 `useI18n()` 会抛错。`useI18nOptional()` 回退到中文。
+
+## 语言怎么定
 
-1. 显式 `locale` prop
-2. `localStorage`（默认 key：`abuilder.locale`）
-3. 浏览器语言（`zh*` → zh-CN，否则 en-US）
+1. 显式 `locale`
+2. `localStorage`（默认 key `abuilder.locale`）
+3. 浏览器语言（`zh*` → `zh-CN`，否则 `en-US`）
 4. 回退 `zh-CN`
 
+文案在 `src/locales/zh-CN.ts` 和 `en-US.ts`。加 key 时两份一起加，缺的 key 会显示 key 本身。
+
 ## 许可证
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arronqzy/i18n",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "Shared Chinese/English i18n for Abuilder (React + Vue)",
   "license": "MIT",
   "type": "module",

package/src/locales/en-US.ts

@@ -111,6 +111,7 @@ export const enUS = {
       importPanelJson: "Import panel JSON",
       exportBlueprint: "Export blueprint",
       importBlueprint: "Import blueprint",
+      apiCollections: "API collections",
       undo: "Undo",
       redo: "Redo",
       bringForward: "Bring forward",
@@ -1163,8 +1164,12 @@ export const enUS = {
       updated: "Updated",
       expand: "Expand scope",
       collapse: "Collapse scope",
-      usageHint1: "Use template strings to reference scope in forms, e.g. {scope?.a||0}, {scope?.name||''}. Supports ?. and || placeholders.",
-      usageHint2: "Array-spread templates [...{scope?.a?.b}], [...{scope?.data?.data?.statusName}]: output comma-separated strings in text fields; expand to n items in chart category arrays (e.g. 3 records → 3 categories).",
+      usageHint1:
+        "Use template strings in forms. scope is data passed between blueprint nodes, e.g. {scope?.a||0}, {scope?.name||''}. system is built-in tools/vars: {system?.time} (dayjs now), {system?.math} (Math), {system?.location} (Location). They nest together, e.g. startTime:{system?.time?.subtract(scope?.value?.days||7,'d')}. Supports ?. and ||.",
+      usageHint2:
+        "Array-spread templates [...{scope?.a?.b}], [...{scope?.data?.data?.statusName}]: comma-separated strings in text fields; expand to n items in chart categories. system is for expression tools, not array spread.",
+      usageHintSystem:
+        "scope vs system: scope is workflow payload data; system is a toolbox (time / math / location). Example: {system?.time?.subtract(system?.math?.random(),'d')}. Mix with scope freely.",
       previewTitle: "Resolved preview",
       previewArray: "Array · {count} item(s)",
       expandPreview: "Expand",
@@ -1296,6 +1301,33 @@ export const enUS = {
       deleteNode: "Delete node",
       deleteEdge: "Delete edge",
     },
+    apiCollection: {
+      managerTitle: "API collections",
+      managerDescription:
+        "Upload local JSON API collections for Fetch nodes when Swagger URLs are blocked by CORS. Choose whether to persist to IndexedDB. String values in url / params / headers / body / baseUrl support {scope?...} templates.",
+      upload: "Upload JSON",
+      create: "Create / paste",
+      downloadTemplate: "Download template",
+      persistLocal: "Persist to IndexedDB",
+      persistLocalHint: "If off, collections stay in memory only and are lost on refresh.",
+      empty: "No collections yet. Download the template, edit it, then upload.",
+      apiCount: "{count} APIs",
+      persisted: "Persisted",
+      memoryOnly: "Memory only",
+      confirmDelete: "Delete this API collection?",
+      sync: "Sync",
+      syncHint:
+        "Match Fetch nodes in the current blueprint by URL (query ignored) and refill method, headers, body, and params. Nodes with unmatched URLs are left unchanged.",
+      syncSuccess: "Updated {count} blueprint node(s)",
+      syncSuccessDetail: "Synced {count} node(s): {names}",
+      syncNone: "No Fetch nodes matched by URL",
+      syncUnavailable: "This panel cannot sync blueprint nodes",
+      editTitle: "Edit API collection",
+      createTitle: "Create API collection",
+      editorDescription:
+        "Edit JSON using the template shape. It is validated before save. String fields (url, params values, headers values, body, baseUrl) may use {scope?...} and resolve from upstream Scope at runtime.",
+      jsonEditor: "JSON",
+    },
     dialog: {
       renameTitle: "Rename blueprint",
       renameDescription: "Change the display name of this library item.",
@@ -1437,11 +1469,13 @@ export const enUS = {
       taskChain: "Task chain",
       allowFalsePropagateDefault: "Allow false-signal propagation: by default false blocks the chain; when on, false signals and errors continue downstream.",
       fetchTitle: "Fetch",
-      fetchHint: "On a true signal, send an HTTP request. URL / headers / body / Base URL can use {scope?...} to read upstream data.",
+      fetchHint:
+        "On a true signal, send an HTTP request. URL / headers / body / Base URL can use {scope?...} for upstream data, and {system?.time} / {system?.math} / {system?.location} for system vars.",
       fetchScopeTitle: "Upstream scope",
       fetchScopeHint:
-        "One upstream node: {scope?.value}, {scope?.id}, {scope?.name}, {scope?.type}. Multiple upstream nodes are keyed by node id, e.g. {scope?.node_abc?.value}. value is the output; other fields are node details. Header templates can live in JSON string values, or the whole field can be {scope?.value?.headers}.",
-      fetchScopeEmpty: "No upstream edges yet. Connect a node to use scope templates for its output and details.",
+        "One upstream node: {scope?.value}, {scope?.id}, {scope?.name}, {scope?.type}. Multiple upstream nodes are keyed by node id, e.g. {scope?.node_abc?.value}. value is the output; other fields are node details. Also {system?.time?.subtract(7,'d')} and nesting with scope. Header templates can live in JSON string values, or the whole field can be {scope?.value?.headers}.",
+      fetchScopeEmpty:
+        "No upstream edges yet. {system?...} still works; connect a node to use scope templates for its output and details.",
       fetchScopePending: "Upstream has not run yet, so value is empty; id / name / type are already available.",
       fetchScopeResolvedUrl: "Resolved URL",
       fetchScopeResolvedHeaders: "Resolved headers",
@@ -1479,6 +1513,33 @@ export const enUS = {
       fillSwaggerUrlFirst: "Enter a Swagger document URL first",
       fillRequestUrlFirst: "Enter a request URL first",
       noMatchingEndpoint: "No matching endpoints",
+      fetchSourceMode: "Config source",
+      fetchSourceDirect: "Manual / Swagger",
+      fetchSourceCollection: "API collection",
+      fetchSourceDirectHint:
+        "Parse endpoints from a Swagger URL, or type the request URL manually. Cross-origin docs may fail to load.",
+      fetchSourceCollectionHint:
+        "Pick a collection and API uploaded under Blueprint → API collections. URL, method, headers, and body are filled in. Collection string values support {scope?...}; hover the API name to see its description.",
+      apiCollectionSelect: "API collection",
+      apiCollectionSelectPlaceholder: "Select an uploaded collection",
+      apiCollectionEmpty: "No collections yet — upload from the Blueprint menu",
+      apiCollectionEndpoint: "API name",
+      apiCollectionEndpointPlaceholder: "Select an API",
+      apiCollectionNoEndpoints: "This collection has no APIs",
+      apiCollectionFilledHint:
+        "Selecting an API fills the form below; you can still edit fields. Hover the API name to see its description.",
+      apiCollectionSyncUpdatedTitle: "Updated",
+      apiCollectionSyncUpdatedSource: "Source: API collection sync",
+      apiCollectionSyncUpdatedCollection: "Collection “{collection}” · API “{endpoint}”",
+      apiCollectionSyncUpdatedFields: "Changed: {fields}",
+      apiCollectionSyncUpdatedNoFieldChange: "Changed: aligned with collection (no field diff)",
+      apiCollectionSyncField: {
+        url: "Request URL",
+        method: "Method",
+        headers: "Headers",
+        body: "Body",
+        apiBaseUrl: "API host / Base URL",
+      },
       swaggerParseFailed: "Failed to parse Swagger document",
       enterSwaggerUrl: "Enter a Swagger document URL",
       cannotFetchSwagger: "Cannot fetch Swagger document",
@@ -1486,12 +1547,17 @@ export const enUS = {
       swaggerHtmlReturned: "Response is HTML; provide an OpenAPI/Swagger JSON URL",
       swaggerInvalidJson: "Swagger document is not valid JSON",
       jsonTitle: "JSON node",
-      jsonHint: "On a true signal, parse the JSON below into an object/array and emit true. Supports {scope?...} templates resolved from upstream scope at runtime. On parse failure emit false.",
-      jsonScopeHint: "Write {scope?.value} anywhere in the JSON; inside strings it is escaped, in value position it becomes a JSON literal.",
-      jsonScopeDeferred: "Contains scope templates; validated after runtime resolution",
+      jsonHint:
+        "On a true signal, parse the JSON below into an object/array and emit true. Supports {scope?...} / {system?...} templates resolved at runtime. On parse failure emit false. Invalid spots are highlighted in red (e.g. curly quotes “”).",
+      jsonScopeHint:
+        "Write {scope?.value} / {system?.time} anywhere in the JSON; inside strings it is escaped, in value position it becomes a JSON literal. Use ASCII double quotes \", not curly “”.",
+      jsonScopeDeferred: "Contains scope/system templates; validated after runtime resolution",
       jsonContent: "JSON content",
       jsonFormatError: "Invalid JSON: {error}",
       jsonFormatOk: "JSON is valid",
+      jsonErrorPreviewHint:
+        "Red highlights below mark problem spots (edit in the box above)",
+      jsonJumpToError: "Jump to error",
       storageTitle: "Storage node",
       storageHint: "On a true signal, write first then read. Skip write if set is empty; output empty if read is empty. When both are configured, set runs before read.",
       storageReadTitle: "Read",

package/src/locales/zh-CN.ts

@@ -110,6 +110,7 @@ export const zhCN = {
       importPanelJson: "导入面板 JSON",
       exportBlueprint: "导出蓝图",
       importBlueprint: "导入蓝图",
+      apiCollections: "接口集合",
       undo: "撤销",
       redo: "重做",
       bringForward: "上移一层",
@@ -1159,8 +1160,12 @@ export const zhCN = {
       updated: "已更新",
       expand: "展开 Scope",
       collapse: "收起 Scope",
-      usageHint1: "表单中可使用模版字符串引用 scope，例如 {scope?.a||0}、{scope?.name||''}。支持 ?. 与 || 占位。",
-      usageHint2: "数组展开模版 [...{scope?.a?.b}]、[...{scope?.data?.data?.statusName}]：在文本字段输出逗号分隔字符串；在图表「类目」等数组字段会展开为 n 个独立项（如 3 条数据对应 3 个类目）。",
+      usageHint1:
+        "表单中可使用模版字符串。scope 是蓝图流程里节点互相传递的数据，例如 {scope?.a||0}、{scope?.name||''}。system 是系统内置工具与变量：{system?.time}（dayjs 当前时间）、{system?.math}（Math）、{system?.location}（Location）。二者可互相嵌套，例如 startTime:{system?.time?.subtract(scope?.value?.days||7,'d')}。支持 ?. 与 || 占位。",
+      usageHint2:
+        "数组展开模版 [...{scope?.a?.b}]、[...{scope?.data?.data?.statusName}]：在文本字段输出逗号分隔字符串；在图表「类目」等数组字段会展开为 n 个独立项（如 3 条数据对应 3 个类目）。system 不用于数组展开，只作表达式工具。",
+      usageHintSystem:
+        "system 与 scope 区别：scope 像流程里的业务数据包；system 像全局工具箱（time / math / location）。可写 {system?.time?.subtract(system?.math?.random(),'d')}，也可与 scope 混用。",
       previewTitle: "解析预览",
       previewArray: "数组 · {count} 项",
       expandPreview: "展开",
@@ -1292,6 +1297,33 @@ export const zhCN = {
       deleteNode: "删除节点",
       deleteEdge: "删除连线",
     },
+    apiCollection: {
+      managerTitle: "接口集合",
+      managerDescription:
+        "上传本地 JSON 接口集合，供数据获取节点在跨域无法拉取 Swagger 时选用。可勾选是否写入 IndexedDB。url / params / headers / body / baseUrl 的字符串值均支持 {scope?...} 模版。",
+      upload: "上传 JSON",
+      create: "新建 / 粘贴",
+      downloadTemplate: "下载模版",
+      persistLocal: "本地化保存到 IndexedDB",
+      persistLocalHint: "关闭后仅保存在当前会话内存，刷新页面会丢失。",
+      empty: "还没有接口集合。可下载模版编辑后再上传。",
+      apiCount: "{count} 个接口",
+      persisted: "已本地化",
+      memoryOnly: "仅内存",
+      confirmDelete: "确定删除该接口集合？",
+      sync: "同步",
+      syncHint:
+        "按 URL（忽略查询参数）匹配当前蓝图中的数据获取节点，回填方法、请求头、请求体与参数；URL 对不上的节点不会改。",
+      syncSuccess: "已同步更新 {count} 个蓝图节点",
+      syncSuccessDetail: "已同步 {count} 个节点：{names}",
+      syncNone: "没有找到 URL 匹配的数据获取节点",
+      syncUnavailable: "当前面板无法同步蓝图节点",
+      editTitle: "编辑接口集合",
+      createTitle: "新建接口集合",
+      editorDescription:
+        "请按模版结构编辑 JSON，保存前会校验类型。字符串字段（url、params 值、headers 值、body、baseUrl）可写 {scope?...}，运行时按上游 Scope 解析。",
+      jsonEditor: "JSON 内容",
+    },
     dialog: {
       renameTitle: "重命名蓝图",
       renameDescription: "修改蓝图库中该项的显示名称。",
@@ -1433,11 +1465,13 @@ export const zhCN = {
       taskChain: "任务链执行",
       allowFalsePropagateDefault: "允许假信号传递：默认假信号会阻塞任务链；开启后继续向下游传递假信号与错误信息。",
       fetchTitle: "数据源获取 (Fetch)",
-      fetchHint: "收到真信号后发起 HTTP 请求。URL / 请求头 / 请求体 / Base URL 可用 {scope?...} 引用上游数据。",
+      fetchHint:
+        "收到真信号后发起 HTTP 请求。URL / 请求头 / 请求体 / Base URL 可用 {scope?...} 引用上游数据，也可用 {system?.time} / {system?.math} / {system?.location} 等系统变量。",
       fetchScopeTitle: "上游输入 Scope",
       fetchScopeHint:
-        "单路上游：{scope?.value}、{scope?.id}、{scope?.name}、{scope?.type}。多路上游按节点 id 取值，例如 {scope?.node_abc?.value}。value 为上游输出，其余为节点详情。请求头可把模板写在 JSON 字符串值内，也可整段写成 {scope?.value?.headers}。",
-      fetchScopeEmpty: "暂无上游连线。连接上游后可用 scope 模板引用其输出与节点信息。",
+        "单路上游：{scope?.value}、{scope?.id}、{scope?.name}、{scope?.type}。多路上游按节点 id 取值，例如 {scope?.node_abc?.value}。value 为上游输出，其余为节点详情。另可用 {system?.time?.subtract(7,'d')} 等系统模版，并可与 scope 嵌套。请求头可把模板写在 JSON 字符串值内，也可整段写成 {scope?.value?.headers}。",
+      fetchScopeEmpty:
+        "暂无上游连线。无 scope 时仍可用 {system?...}；连接上游后可用 scope 模板引用其输出与节点信息。",
       fetchScopePending: "上游尚未执行，value 暂空；id / name / type 已可引用。",
       fetchScopeResolvedUrl: "解析后的 URL",
       fetchScopeResolvedHeaders: "解析后的请求头",
@@ -1475,6 +1509,31 @@ export const zhCN = {
       fillSwaggerUrlFirst: "请先填写 Swagger 文档 URL",
       fillRequestUrlFirst: "请先填写请求 URL",
       noMatchingEndpoint: "无匹配接口",
+      fetchSourceMode: "配置来源",
+      fetchSourceDirect: "手动 / Swagger",
+      fetchSourceCollection: "接口集合",
+      fetchSourceDirectHint: "填写 Swagger 文档地址解析接口，或手动输入请求 URL。跨域时文档地址可能无法请求。",
+      fetchSourceCollectionHint:
+        "从顶栏「蓝图 → 接口集合」上传的 JSON 中选择集合与接口，自动回填 URL / 方法 / 请求头 / 请求体。集合内字符串值支持 {scope?...}；悬停接口名称可查看 description。",
+      apiCollectionSelect: "接口集合",
+      apiCollectionSelectPlaceholder: "选择已上传的集合",
+      apiCollectionEmpty: "暂无集合，请先在蓝图菜单上传",
+      apiCollectionEndpoint: "接口名称",
+      apiCollectionEndpointPlaceholder: "选择接口",
+      apiCollectionNoEndpoints: "该集合没有接口",
+      apiCollectionFilledHint: "选中接口后会回填下方表单，仍可继续修改。悬停接口名称可查看接口说明。",
+      apiCollectionSyncUpdatedTitle: "已更新",
+      apiCollectionSyncUpdatedSource: "更新来源：数据集合更新",
+      apiCollectionSyncUpdatedCollection: "集合「{collection}」· 接口「{endpoint}」",
+      apiCollectionSyncUpdatedFields: "更新内容：{fields}",
+      apiCollectionSyncUpdatedNoFieldChange: "更新内容：与集合对齐（字段无变化）",
+      apiCollectionSyncField: {
+        url: "请求 URL",
+        method: "请求方法",
+        headers: "请求头",
+        body: "请求体",
+        apiBaseUrl: "API 主机 / Base URL",
+      },
       swaggerParseFailed: "Swagger 文档解析失败",
       enterSwaggerUrl: "请输入 Swagger 文档 URL",
       cannotFetchSwagger: "无法请求 Swagger 文档",
@@ -1482,12 +1541,16 @@ export const zhCN = {
       swaggerHtmlReturned: "返回内容为 HTML，请填写 OpenAPI/Swagger 的 JSON 地址",
       swaggerInvalidJson: "Swagger 文档不是有效的 JSON",
       jsonTitle: "JSON 节点",
-      jsonHint: "收到真信号后，将下方 JSON 解析为 object/array 并发出真信号；支持 {scope?...} 模板（运行时按上游 scope 替换）。解析失败则发出假信号。",
-      jsonScopeHint: "可在 JSON 任意位置写 {scope?.value}；位于字符串内会转义，位于值位置会写入 JSON 字面量。",
-      jsonScopeDeferred: "含 scope 模板，将在运行时解析后校验",
+      jsonHint:
+        "收到真信号后，将下方 JSON 解析为 object/array 并发出真信号；支持 {scope?...} / {system?...} 模板（运行时替换）。解析失败则发出假信号。不合规处会在编辑器内标红（如误用中文引号 “”）。",
+      jsonScopeHint:
+        "可在 JSON 任意位置写 {scope?.value} / {system?.time}；位于字符串内会转义，位于值位置会写入 JSON 字面量。请使用英文双引号 \"，避免中文 “”。",
+      jsonScopeDeferred: "含 scope/system 模板，将在运行时解析后校验",
       jsonContent: "JSON 内容",
       jsonFormatError: "JSON 格式错误：{error}",
       jsonFormatOk: "JSON 格式正确",
+      jsonErrorPreviewHint: "下方预览标红为异常位置（编辑请用上方输入框）",
+      jsonJumpToError: "定位到错误",
       storageTitle: "存储节点",
       storageHint: "收到真信号后先写入再读取。不配置设置则不写入；不配置读取则输出空。设置与读取同时配置时按「先设置、后读取」执行。",
       storageReadTitle: "读取",

package/src/react/I18nProvider.tsx

@@ -81,6 +81,25 @@ export function useI18n(): I18nContextValue {
   return ctx;
 }
 
+/** Whether the nearest I18nProvider from *this* package instance is present. */
+export function useHasI18nProvider(): boolean {
+  return useContext(I18nContext) != null;
+}
+
+/**
+ * If no I18nProvider from this package is above, wrap children with one.
+ * Fixes Umi/npm duplicate-`@arronqzy/i18n` cases where the panel Provider
+ * comes from a different copy than react-blueprint's `useI18n`.
+ */
+export function EnsureI18nProvider({
+  children,
+  ...providerProps
+}: I18nProviderProps) {
+  const hasProvider = useHasI18nProvider();
+  if (hasProvider) return <>{children}</>;
+  return <I18nProvider {...providerProps}>{children}</I18nProvider>;
+}
+
 /** Safe hook: returns zh-CN translator when outside provider (for utilities). */
 export function useI18nOptional(): I18nContextValue {
   const ctx = useContext(I18nContext);

package/src/react/index.ts

@@ -1,2 +1,2 @@
-export { I18nProvider, useI18n, useI18nOptional } from "./I18nProvider";
+export { I18nProvider, EnsureI18nProvider, useI18n, useI18nOptional, useHasI18nProvider } from "./I18nProvider";
 export type { I18nContextValue, I18nProviderProps } from "./I18nProvider";