From b415227835976765a008249afea744f9e9440a82 Mon Sep 17 00:00:00 2001 From: RiskeyL <7a8y@163.com> Date: Fri, 10 Apr 2026 14:49:17 +0800 Subject: [PATCH 1/5] docs: document datasource_info_list per-type schemas for Run Pipeline API --- en/api-reference/openapi_knowledge.json | 189 +++++++++++++++++++++++- 1 file changed, 183 insertions(+), 6 deletions(-) diff --git a/en/api-reference/openapi_knowledge.json b/en/api-reference/openapi_knowledge.json index fbcbb4b92..16c0062e3 100644 --- a/en/api-reference/openapi_knowledge.json +++ b/en/api-reference/openapi_knowledge.json @@ -5758,20 +5758,124 @@ "datasource_type": { "type": "string", "enum": [ - "online_document", "local_file", + "online_document", "website_crawl", "online_drive" ], - "description": "Type of the datasource." + "description": "Type of the datasource. Determines which fields are expected in `datasource_info_list` items." }, "datasource_info_list": { "type": "array", + "description": "List of datasource objects to process. The expected item structure depends on `datasource_type`.", "items": { - "type": "object", - "additionalProperties": true - }, - "description": "List of datasource information objects for the pipeline to process." + "oneOf": [ + { + "title": "Local File", + "type": "object", + "required": [ + "reference" + ], + "properties": { + "reference": { + "type": "string", + "description": "UUID of the uploaded file, returned by the [Upload Pipeline File](/api-reference/knowledge-pipeline/upload-pipeline-file) endpoint. `related_id` is accepted as an alias." + }, + "name": { + "type": "string", + "description": "Document title. Defaults to `\"untitled\"`." + } + } + }, + { + "title": "Online Document", + "type": "object", + "required": [ + "workspace_id", + "page" + ], + "properties": { + "workspace_id": { + "type": "string", + "description": "ID of the workspace or database in the external platform (e.g., a Notion workspace ID)." + }, + "page": { + "type": "object", + "description": "Page details.", + "required": [ + "page_id", + "type" + ], + "properties": { + "page_id": { + "type": "string", + "description": "Page identifier." + }, + "type": { + "type": "string", + "description": "Page type defined by the datasource plugin (e.g., `\"page\"`, `\"database\"`)." + }, + "page_name": { + "type": "string", + "description": "Display name. Defaults to `\"untitled\"`." + } + } + }, + "credential_id": { + "type": "string", + "description": "Credential for authentication." + } + } + }, + { + "title": "Website Crawl", + "type": "object", + "required": [ + "url" + ], + "properties": { + "url": { + "type": "string", + "description": "URL to crawl." + }, + "title": { + "type": "string", + "description": "Used as the document name. Defaults to `\"untitled\"`." + } + } + }, + { + "title": "Online Drive", + "type": "object", + "required": [ + "id", + "type" + ], + "properties": { + "id": { + "type": "string", + "description": "File or folder ID." + }, + "type": { + "type": "string", + "enum": [ + "file", + "folder" + ], + "description": "Whether this entry is a single file or a folder to expand." + }, + "bucket": { + "type": "string", + "description": "Storage bucket name. Required by some drive providers (e.g., S3-compatible stores); omit if the provider does not use buckets." + }, + "name": { + "type": "string", + "description": "File name. Defaults to `\"untitled\"`." + } + } + } + ] + } }, "start_node_id": { "type": "string", @@ -5790,6 +5894,79 @@ "description": "Response mode for the pipeline execution. `streaming` returns a Server-Sent Events stream, `blocking` waits and returns the complete result." } } + }, + "examples": { + "local_file": { + "summary": "Request Example—Local file", + "value": { + "inputs": {}, + "datasource_type": "local_file", + "datasource_info_list": [ + { + "reference": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "quarterly-report.pdf" + } + ], + "start_node_id": "1719288585006", + "is_published": true, + "response_mode": "blocking" + } + }, + "online_document": { + "summary": "Request Example—Online document", + "value": { + "inputs": {}, + "datasource_type": "online_document", + "datasource_info_list": [ + { + "workspace_id": "ws-abc123", + "page": { + "page_id": "pg-def456", + "type": "page", + "page_name": "Product Roadmap" + }, + "credential_id": "cred-789xyz" + } + ], + "start_node_id": "1719288585006", + "is_published": true, + "response_mode": "streaming" + } + }, + "website_crawl": { + "summary": "Request Example—Website crawl", + "value": { + "inputs": {}, + "datasource_type": "website_crawl", + "datasource_info_list": [ + { + "url": "https://example.com/docs/getting-started", + "title": "Getting Started Guide" + } + ], + "start_node_id": "1719288585006", + "is_published": true, + "response_mode": "blocking" + } + }, + "online_drive": { + "summary": "Request Example—Online drive", + "value": { + "inputs": {}, + "datasource_type": "online_drive", + "datasource_info_list": [ + { + "id": "file-abc123", + "type": "file", + "bucket": "my-bucket", + "name": "meeting-notes.docx" + } + ], + "start_node_id": "1719288585006", + "is_published": true, + "response_mode": "blocking" + } + } } } } From 7f8da394e25a3a39ed2e232ae238d49d6c34c403 Mon Sep 17 00:00:00 2001 From: RiskeyL <7a8y@163.com> Date: Fri, 10 Apr 2026 14:49:37 +0800 Subject: [PATCH 2/5] docs: improve Run Pipeline parameter descriptions and SSE event documentation --- en/api-reference/openapi_knowledge.json | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/en/api-reference/openapi_knowledge.json b/en/api-reference/openapi_knowledge.json index 16c0062e3..9a75a4c37 100644 --- a/en/api-reference/openapi_knowledge.json +++ b/en/api-reference/openapi_knowledge.json @@ -5753,7 +5753,7 @@ "inputs": { "type": "object", "additionalProperties": true, - "description": "Input variables for the pipeline." + "description": "Key-value pairs for pipeline input variables defined in the workflow. Pass `{}` if the pipeline has no input variables." }, "datasource_type": { "type": "string", @@ -5823,7 +5823,7 @@ }, "credential_id": { "type": "string", - "description": "Credential for authentication." + "description": "Credential for authenticating with the external platform. Managed via the Dify console. If omitted, the provider's default credential is used." } } }, @@ -5883,7 +5883,7 @@ }, "is_published": { "type": "boolean", - "description": "Whether to run the published or draft version of the pipeline. `true` runs the published version, `false` runs the draft." + "description": "Whether to run the published or draft version of the pipeline. `true` runs the latest published version; `false` runs the current draft (useful for testing unpublished changes)." }, "response_mode": { "type": "string", @@ -5978,7 +5978,7 @@ "text/event-stream": { "schema": { "type": "string", - "description": "Server-Sent Events stream containing pipeline execution progress and results. Returned when `response_mode` is `streaming`." + "description": "Server-Sent Events stream. Returned when `response_mode` is `streaming`.\n\nEach line is `data: {JSON}\\n\\n`. Key events: `workflow_started` (execution began), `node_started` / `node_finished` (per-node progress with `node_id`, `node_type`, `status`, `inputs`, `outputs`), `workflow_finished` (final result with `status`, `outputs`, `total_tokens`, `elapsed_time`), `ping` (keepalive). " } }, "application/json": { From 0df1bde719104cf6dc441c6ed9d07412d0c8d3a0 Mon Sep 17 00:00:00 2001 From: RiskeyL <7a8y@163.com> Date: Fri, 10 Apr 2026 14:59:15 +0800 Subject: [PATCH 3/5] translate: sync zh/ja pipeline API specs with English schema updates --- ja/api-reference/openapi_knowledge.json | 197 ++++++++++++++++++++++-- zh/api-reference/openapi_knowledge.json | 197 ++++++++++++++++++++++-- 2 files changed, 374 insertions(+), 20 deletions(-) diff --git a/ja/api-reference/openapi_knowledge.json b/ja/api-reference/openapi_knowledge.json index dd8064013..eeaf905ec 100644 --- a/ja/api-reference/openapi_knowledge.json +++ b/ja/api-reference/openapi_knowledge.json @@ -5753,25 +5753,129 @@ "inputs": { "type": "object", "additionalProperties": true, - "description": "パイプラインの入力変数です。" + "description": "パイプライン入力変数のキーと値のペア。ワークフローで定義されたパイプライン変数に対応します。入力変数がない場合は `{}` を渡してください。" }, "datasource_type": { "type": "string", "enum": [ - "online_document", "local_file", + "online_document", "website_crawl", "online_drive" ], - "description": "データソースの種類です。" + "description": "データソースのタイプ。`datasource_info_list` の各項目に必要なフィールドを決定します。" }, "datasource_info_list": { "type": "array", + "description": "処理対象のデータソースオブジェクトのリストです。項目の構造は `datasource_type` によって異なります。", "items": { - "type": "object", - "additionalProperties": true - }, - "description": "パイプラインが処理するデータソース情報オブジェクトのリストです。" + "oneOf": [ + { + "title": "Local File", + "type": "object", + "required": [ + "reference" + ], + "properties": { + "reference": { + "type": "string", + "description": "アップロードされたファイルの UUID。[パイプラインファイルアップロード](/api-reference/knowledge-pipeline/upload-pipeline-file)エンドポイントから返されます。`related_id` もエイリアスとして使用可能です。" + }, + "name": { + "type": "string", + "description": "ドキュメントのタイトルです。デフォルトは `\"untitled\"` です。" + } + } + }, + { + "title": "Online Document", + "type": "object", + "required": [ + "workspace_id", + "page" + ], + "properties": { + "workspace_id": { + "type": "string", + "description": "外部プラットフォームのワークスペースまたはデータベース ID（例：Notion のワークスペース ID）。" + }, + "page": { + "type": "object", + "description": "ページの詳細です。", + "required": [ + "page_id", + "type" + ], + "properties": { + "page_id": { + "type": "string", + "description": "ページ識別子です。" + }, + "type": { + "type": "string", + "description": "データソースプラグインで定義されたページタイプ（例：`\"page\"`、`\"database\"`）。" + }, + "page_name": { + "type": "string", + "description": "表示名です。デフォルトは `\"untitled\"` です。" + } + } + }, + "credential_id": { + "type": "string", + "description": "外部プラットフォームとの認証用クレデンシャルです。Dify コンソールで管理します。省略した場合、プロバイダーのデフォルトクレデンシャルが使用されます。" + } + } + }, + { + "title": "Website Crawl", + "type": "object", + "required": [ + "url" + ], + "properties": { + "url": { + "type": "string", + "description": "クロール対象の URL です。" + }, + "title": { + "type": "string", + "description": "ドキュメント名として使用されます。デフォルトは `\"untitled\"` です。" + } + } + }, + { + "title": "Online Drive", + "type": "object", + "required": [ + "id", + "type" + ], + "properties": { + "id": { + "type": "string", + "description": "ファイルまたはフォルダの ID です。" + }, + "type": { + "type": "string", + "enum": [ + "file", + "folder" + ], + "description": "この項目が単一ファイルか、展開対象のフォルダかを指定します。" + }, + "bucket": { + "type": "string", + "description": "ストレージバケット名です。一部のドライブプロバイダー（S3 互換ストレージなど）で必要です。プロバイダーがバケットを使用しない場合は省略できます。" + }, + "name": { + "type": "string", + "description": "ファイル名です。デフォルトは `\"untitled\"` です。" + } + } + } + ] + } }, "start_node_id": { "type": "string", @@ -5779,7 +5883,7 @@ }, "is_published": { "type": "boolean", - "description": "パイプラインの公開バージョンとドラフトバージョンのどちらを実行するかを指定します。`true` は公開バージョン、`false` はドラフトを実行します。" + "description": "パイプラインの公開版またはドラフト版のどちらを実行するかを指定します。`true` は最新の公開版を実行し、`false` は現在のドラフトを実行します（未公開の変更をテストする場合に便利です）。" }, "response_mode": { "type": "string", @@ -5787,7 +5891,80 @@ "streaming", "blocking" ], - "description": "パイプライン実行のレスポンスモードです。`streaming` はサーバー送信イベントストリームを返し、`blocking` は完了を待って完全な結果を返します。" + "description": "パイプライン実行のレスポンスモードです。`streaming` は Server-Sent Events ストリームを返し、`blocking` は完了まで待機して完全な結果を返します。" + } + } + }, + "examples": { + "local_file": { + "summary": "リクエスト例—ローカルファイル", + "value": { + "inputs": {}, + "datasource_type": "local_file", + "datasource_info_list": [ + { + "reference": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "quarterly-report.pdf" + } + ], + "start_node_id": "1719288585006", + "is_published": true, + "response_mode": "blocking" + } + }, + "online_document": { + "summary": "リクエスト例—オンラインドキュメント", + "value": { + "inputs": {}, + "datasource_type": "online_document", + "datasource_info_list": [ + { + "workspace_id": "ws-abc123", + "page": { + "page_id": "pg-def456", + "type": "page", + "page_name": "Product Roadmap" + }, + "credential_id": "cred-789xyz" + } + ], + "start_node_id": "1719288585006", + "is_published": true, + "response_mode": "streaming" + } + }, + "website_crawl": { + "summary": "リクエスト例—ウェブサイトクロール", + "value": { + "inputs": {}, + "datasource_type": "website_crawl", + "datasource_info_list": [ + { + "url": "https://example.com/docs/getting-started", + "title": "Getting Started Guide" + } + ], + "start_node_id": "1719288585006", + "is_published": true, + "response_mode": "blocking" + } + }, + "online_drive": { + "summary": "リクエスト例—オンラインドライブ", + "value": { + "inputs": {}, + "datasource_type": "online_drive", + "datasource_info_list": [ + { + "id": "file-abc123", + "type": "file", + "bucket": "my-bucket", + "name": "meeting-notes.docx" + } + ], + "start_node_id": "1719288585006", + "is_published": true, + "response_mode": "blocking" } } } @@ -5801,7 +5978,7 @@ "text/event-stream": { "schema": { "type": "string", - "description": "パイプライン実行の進捗と結果を含むサーバー送信イベントストリームです。`response_mode` が `streaming` の場合に返されます。" + "description": "Server-Sent Events ストリームです。各行は `data: {JSON}\\n\\n` 形式です。主要なイベント：`workflow_started`（実行開始）、`node_started` / `node_finished`（ノードごとの進捗、`node_id`、`node_type`、`status`、`inputs`、`outputs` を含む）、`workflow_finished`（最終結果、`status`、`outputs`、`total_tokens`、`elapsed_time` を含む）、`ping`（キープアライブ）。" } }, "application/json": { diff --git a/zh/api-reference/openapi_knowledge.json b/zh/api-reference/openapi_knowledge.json index eccb8ac22..13d3312f5 100644 --- a/zh/api-reference/openapi_knowledge.json +++ b/zh/api-reference/openapi_knowledge.json @@ -5753,33 +5753,137 @@ "inputs": { "type": "object", "additionalProperties": true, - "description": "流水线的输入变量。" + "description": "流水线输入变量的键值对，对应工作流中定义的流水线变量。如果流水线没有输入变量，传 `{}`。" }, "datasource_type": { "type": "string", "enum": [ - "online_document", "local_file", + "online_document", "website_crawl", "online_drive" ], - "description": "数据源类型。" + "description": "数据源类型。决定 `datasource_info_list` 中条目所需的字段。" }, "datasource_info_list": { "type": "array", + "description": "待处理的数据源对象列表。条目结构取决于 `datasource_type`。", "items": { - "type": "object", - "additionalProperties": true - }, - "description": "供流水线处理的数据源信息对象列表。" + "oneOf": [ + { + "title": "Local File", + "type": "object", + "required": [ + "reference" + ], + "properties": { + "reference": { + "type": "string", + "description": "已上传文件的 UUID，由[上传流水线文件](/api-reference/knowledge-pipeline/upload-pipeline-file)端点返回。`related_id` 可作为别名使用。" + }, + "name": { + "type": "string", + "description": "文档标题。默认为 `\"untitled\"`。" + } + } + }, + { + "title": "Online Document", + "type": "object", + "required": [ + "workspace_id", + "page" + ], + "properties": { + "workspace_id": { + "type": "string", + "description": "外部平台中的工作空间或数据库 ID（例如 Notion 工作空间 ID）。" + }, + "page": { + "type": "object", + "description": "页面详情。", + "required": [ + "page_id", + "type" + ], + "properties": { + "page_id": { + "type": "string", + "description": "页面标识符。" + }, + "type": { + "type": "string", + "description": "由数据源插件定义的页面类型（例如 `\"page\"`、`\"database\"`）。" + }, + "page_name": { + "type": "string", + "description": "显示名称。默认为 `\"untitled\"`。" + } + } + }, + "credential_id": { + "type": "string", + "description": "用于与外部平台认证的凭证。通过 Dify 控制台管理。如省略，则使用该供应商的默认凭证。" + } + } + }, + { + "title": "Website Crawl", + "type": "object", + "required": [ + "url" + ], + "properties": { + "url": { + "type": "string", + "description": "待爬取的 URL。" + }, + "title": { + "type": "string", + "description": "用作文档名称。默认为 `\"untitled\"`。" + } + } + }, + { + "title": "Online Drive", + "type": "object", + "required": [ + "id", + "type" + ], + "properties": { + "id": { + "type": "string", + "description": "文件或文件夹 ID。" + }, + "type": { + "type": "string", + "enum": [ + "file", + "folder" + ], + "description": "该条目是单个文件还是待展开的文件夹。" + }, + "bucket": { + "type": "string", + "description": "存储桶名称。部分存储供应商需要此字段（例如 S3 兼容存储）；如果供应商不使用存储桶，可省略。" + }, + "name": { + "type": "string", + "description": "文件名称。默认为 `\"untitled\"`。" + } + } + } + ] + } }, "start_node_id": { "type": "string", - "description": "流水线开始执行的节点 ID。" + "description": "流水线开始执行的数据源节点 ID。" }, "is_published": { "type": "boolean", - "description": "运行流水线的已发布版本还是草稿版本。`true` 运行已发布版本，`false` 运行草稿版本。" + "description": "运行流水线的已发布版本还是草稿版本。`true` 运行最新已发布版本；`false` 运行当前草稿（适用于测试未发布的更改）。" }, "response_mode": { "type": "string", @@ -5790,6 +5894,79 @@ "description": "流水线执行的响应模式。`streaming` 返回服务器发送事件流，`blocking` 等待并返回完整结果。" } } + }, + "examples": { + "local_file": { + "summary": "请求示例—本地文件", + "value": { + "inputs": {}, + "datasource_type": "local_file", + "datasource_info_list": [ + { + "reference": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", + "name": "quarterly-report.pdf" + } + ], + "start_node_id": "1719288585006", + "is_published": true, + "response_mode": "blocking" + } + }, + "online_document": { + "summary": "请求示例—在线文档", + "value": { + "inputs": {}, + "datasource_type": "online_document", + "datasource_info_list": [ + { + "workspace_id": "ws-abc123", + "page": { + "page_id": "pg-def456", + "type": "page", + "page_name": "Product Roadmap" + }, + "credential_id": "cred-789xyz" + } + ], + "start_node_id": "1719288585006", + "is_published": true, + "response_mode": "streaming" + } + }, + "website_crawl": { + "summary": "请求示例—网站爬取", + "value": { + "inputs": {}, + "datasource_type": "website_crawl", + "datasource_info_list": [ + { + "url": "https://example.com/docs/getting-started", + "title": "Getting Started Guide" + } + ], + "start_node_id": "1719288585006", + "is_published": true, + "response_mode": "blocking" + } + }, + "online_drive": { + "summary": "请求示例—在线存储", + "value": { + "inputs": {}, + "datasource_type": "online_drive", + "datasource_info_list": [ + { + "id": "file-abc123", + "type": "file", + "bucket": "my-bucket", + "name": "meeting-notes.docx" + } + ], + "start_node_id": "1719288585006", + "is_published": true, + "response_mode": "blocking" + } + } } } } @@ -5801,7 +5978,7 @@ "text/event-stream": { "schema": { "type": "string", - "description": "包含流水线执行进度和结果的服务器发送事件流。当 `response_mode` 为 `streaming` 时返回。" + "description": "服务器发送事件流。每行格式为 `data: {JSON}\\n\\n`。主要事件：`workflow_started`（执行开始）、`node_started` / `node_finished`（逐节点进度，包含 `node_id`、`node_type`、`status`、`inputs`、`outputs`）、`workflow_finished`（最终结果，包含 `status`、`outputs`、`total_tokens`、`elapsed_time`）、`ping`（心跳保活）。" } }, "application/json": { From bedc72a31a7958f297d7859d23ec9ad1da082201 Mon Sep 17 00:00:00 2001 From: RiskeyL <7a8y@163.com> Date: Fri, 10 Apr 2026 15:35:43 +0800 Subject: [PATCH 4/5] fix: address Copilot's PR review feedback on pipeline API docs --- en/api-reference/openapi_knowledge.json | 4 ++-- ja/api-reference/openapi_knowledge.json | 2 +- zh/api-reference/openapi_knowledge.json | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/en/api-reference/openapi_knowledge.json b/en/api-reference/openapi_knowledge.json index 9a75a4c37..fdd24b0af 100644 --- a/en/api-reference/openapi_knowledge.json +++ b/en/api-reference/openapi_knowledge.json @@ -5779,7 +5779,7 @@ "properties": { "reference": { "type": "string", - "description": "UUID of the uploaded file, returned by the [Upload Pipeline File](/api-reference/knowledge-pipeline/upload-pipeline-file) endpoint. `related_id` is accepted as an alias." + "description": "Use the `id` returned by the [Upload Pipeline File](/api-reference/knowledge-pipeline/upload-pipeline-file) endpoint. `related_id` is accepted as an alias." }, "name": { "type": "string", @@ -5978,7 +5978,7 @@ "text/event-stream": { "schema": { "type": "string", - "description": "Server-Sent Events stream. Returned when `response_mode` is `streaming`.\n\nEach line is `data: {JSON}\\n\\n`. Key events: `workflow_started` (execution began), `node_started` / `node_finished` (per-node progress with `node_id`, `node_type`, `status`, `inputs`, `outputs`), `workflow_finished` (final result with `status`, `outputs`, `total_tokens`, `elapsed_time`), `ping` (keepalive). " + "description": "Server-Sent Events stream. Returned when `response_mode` is `streaming`.\n\nEach line is `data: {JSON}\\n\\n`. Key events: `workflow_started` (execution began), `node_started` / `node_finished` (per-node progress with `node_id`, `node_type`, `status`, `inputs`, `outputs`), `workflow_finished` (final result with `status`, `outputs`, `total_tokens`, `elapsed_time`), `ping` (keepalive)." } }, "application/json": { diff --git a/ja/api-reference/openapi_knowledge.json b/ja/api-reference/openapi_knowledge.json index eeaf905ec..617e176ac 100644 --- a/ja/api-reference/openapi_knowledge.json +++ b/ja/api-reference/openapi_knowledge.json @@ -5779,7 +5779,7 @@ "properties": { "reference": { "type": "string", - "description": "アップロードされたファイルの UUID。[パイプラインファイルアップロード](/api-reference/knowledge-pipeline/upload-pipeline-file)エンドポイントから返されます。`related_id` もエイリアスとして使用可能です。" + "description": "[パイプラインファイルアップロード](/api-reference/ナレッジパイプライン/パイプラインファイルをアップロード) エンドポイントから返される `id` を使用してください。`related_id` もエイリアスとして使用可能です。" }, "name": { "type": "string", diff --git a/zh/api-reference/openapi_knowledge.json b/zh/api-reference/openapi_knowledge.json index 13d3312f5..3f833a8ce 100644 --- a/zh/api-reference/openapi_knowledge.json +++ b/zh/api-reference/openapi_knowledge.json @@ -5779,7 +5779,7 @@ "properties": { "reference": { "type": "string", - "description": "已上传文件的 UUID，由[上传流水线文件](/api-reference/knowledge-pipeline/upload-pipeline-file)端点返回。`related_id` 可作为别名使用。" + "description": "使用 [上传流水线文件](/api-reference/知识流水线/上传流水线文件) 端点返回的 `id`。`related_id` 可作为别名使用。" }, "name": { "type": "string", From 0cf66ebb9aa7fc9df7cb96240734c35b4f2af68b Mon Sep 17 00:00:00 2001 From: RiskeyL <7a8y@163.com> Date: Fri, 10 Apr 2026 15:36:18 +0800 Subject: [PATCH 5/5] style: add punctuation spacing and API cross-link rules to translation guides --- tools/translate/formatting-ja.md | 18 ++++++++++++++++++ tools/translate/formatting-zh.md | 19 +++++++++++++++++++ 2 files changed, 37 insertions(+) diff --git a/tools/translate/formatting-ja.md b/tools/translate/formatting-ja.md index 69a91d0b4..9a1bfa7d6 100644 --- a/tools/translate/formatting-ja.md +++ b/tools/translate/formatting-ja.md @@ -30,6 +30,14 @@ Insert a space between Japanese characters and adjacent Latin letters, numbers, This rule also applies before Japanese particles (を、は、が、の、に、で、と) when they follow Latin text. +**Exception:** No space between two adjacent punctuation marks. Punctuation includes full-width CJK marks (。、：）, backticks, and markdown brackets (`[`, `]`, `(`, `)`). + +| Correct | Incorrect | +|:--------|:----------| +| `"page"`、`"database"` | `"page"` 、 `"database"` | +| 参照（[リンク](/path)）。 | 参照（ [リンク](/path) ）。 | +| です。`streaming` モード | です。 `streaming` モード | + ## Punctuation Use full-width punctuation in Japanese text: @@ -69,6 +77,16 @@ No space is needed when bold text is adjacent to punctuation or the start of a l For cross-links to other documentation pages, change the `/en/` path prefix in the English source to `/ja/`. +### API Reference Cross-Links + +In OpenAPI spec descriptions, cross-links use the pattern `/api-reference/{tag-kebab}/{summary-kebab}`. When translating, replace both the tag and summary segments with their translated equivalents from the target language's spec. + +| English | Japanese | +|:--------|:---------| +| `/api-reference/knowledge-pipeline/upload-pipeline-file` | `/api-reference/ナレッジパイプライン/パイプラインファイルをアップロード` | + +The translated tag and summary must match the `tags` and `summary` fields in the corresponding endpoint of the ja OpenAPI spec. + ## Katakana Conventions Use katakana for foreign loanwords and technical terms that have established katakana equivalents. Refer to the glossary for standard translations. diff --git a/tools/translate/formatting-zh.md b/tools/translate/formatting-zh.md index 18afefb3d..426ec5092 100644 --- a/tools/translate/formatting-zh.md +++ b/tools/translate/formatting-zh.md @@ -15,6 +15,15 @@ Always insert a space between Chinese characters and adjacent Latin letters, num | 设置 `Temperature` 参数 | 设置`Temperature`参数 | | 支持 3 种模型 | 支持3种模型 | +**Exception:** No space between two adjacent punctuation marks. Punctuation includes full-width CJK marks (。、，；：）, backticks, and markdown brackets (`[`, `]`, `(`, `)`). + +| Correct | Incorrect | +|:--------|:----------| +| 默认为 `"untitled"`。 | 默认为 `"untitled"` 。 | +| `"page"`、`"database"` | `"page"` 、 `"database"` | +| 详见（[链接](/path)）。 | 详见（ [链接](/path) ）。 | +| 返回。`streaming` 模式 | 返回。 `streaming` 模式 | + ## Punctuation Use full-width punctuation in Chinese text: @@ -89,6 +98,16 @@ No space is needed when link text is adjacent to punctuation. For cross-links to other documentation pages, change the `/en/` path prefix in the English source to `/zh/`. +### API Reference Cross-Links + +In OpenAPI spec descriptions, cross-links use the pattern `/api-reference/{tag-kebab}/{summary-kebab}`. When translating, replace both the tag and summary segments with their translated equivalents from the target language's spec. + +| English | Chinese | +|:--------|:--------| +| `/api-reference/knowledge-pipeline/upload-pipeline-file` | `/api-reference/知识流水线/上传流水线文件` | + +The translated tag and summary must match the `tags` and `summary` fields in the corresponding endpoint of the zh OpenAPI spec. + ## Numbers - Use Arabic numerals (1, 2, 3), not Chinese numerals (一、二、三), for