diff --git a/.claude/skills/dify-docs-format-check-cjk/SKILL.md b/.claude/skills/dify-docs-format-check-cjk/SKILL.md index 637b49096..bd125e280 100644 --- a/.claude/skills/dify-docs-format-check-cjk/SKILL.md +++ b/.claude/skills/dify-docs-format-check-cjk/SKILL.md @@ -12,7 +12,7 @@ description: > ## Purpose -Verify changed Chinese (`zh/`) and Japanese (`ja/`) documentation against every rule in: +Verify Chinese (`zh/`) and Japanese (`ja/`) documentation against every rule in: - `writing-guides/formatting-guide.md` — general rules - `tools/translate/formatting-zh.md` — Chinese-specific rules @@ -22,13 +22,13 @@ Mechanical rules are enforced by the linter script (`check-format-cjk.py`); judg ## Before Starting -Detect changed documentation files by combining: +Audit the entire file, not just the diff. Default to files currently under review, detected via: - `git diff --name-only` - `git diff --cached --name-only` - Untracked files from `git status --porcelain` (lines starting with `??`) -Filter for `.mdx` and `.md` files under `zh/` or `ja/`. If no changed files are detected, ask the user which files to check. +Filter for `.mdx` and `.md` files under `zh/` or `ja/`. If no files are detected, ask the user which files to check. Because translations are typically produced as a zh/ja pair from the same English source, it is natural to audit both languages in a single session. diff --git a/.claude/skills/dify-docs-format-check-cjk/check-format-cjk.py b/.claude/skills/dify-docs-format-check-cjk/check-format-cjk.py index 54d4b86e8..ed5f25dc6 100644 --- a/.claude/skills/dify-docs-format-check-cjk/check-format-cjk.py +++ b/.claude/skills/dify-docs-format-check-cjk/check-format-cjk.py @@ -57,6 +57,9 @@ def _strip_inline_code(line: str) -> str: def _strip_code_and_urls(line: str) -> str: s = INLINE_CODE_RE.sub('', line) + # collapse markdown image syntax ![alt](url) -> alt first so the leading + # `!` doesn't survive as prose punctuation adjacent to the alt text + s = re.sub(r'!\[([^\]\n]+)\]\([^)\n]+\)', r'\1', s) # collapse markdown link syntax [text](url) -> text so the bracket and # paren characters don't count as prose punctuation s = re.sub(r'\[([^\]\n]+)\]\([^)\n]+\)', r'\1', s) @@ -500,9 +503,11 @@ def check_cjk_bold_spacing(lines: list[str]) -> list[Violation]: vs: list[Violation] = [] in_fence = False # Bold adjacent to CJK without space: X**bold** or **bold**X where X is - # CJK and no space between. - pat_after = re.compile(rf'{CJK}\*\*[^*\n]+?\*\*') - pat_before = re.compile(rf'\*\*[^*\n]+?\*\*{CJK}') + # CJK and no space between. Match each complete **bold** span first, then + # inspect its outer neighbors so the closing `**` of one bold is never + # mistaken for the opening `**` of a later bold on the same line. + bold_pat = re.compile(r'\*\*[^*\n]+?\*\*') + cjk_re = re.compile(CJK) for i, line in enumerate(lines, 1): if FENCE_RE.match(line): in_fence = not in_fence @@ -510,7 +515,16 @@ def check_cjk_bold_spacing(lines: list[str]) -> list[Violation]: if in_fence: continue s = _strip_inline_code(line) - if pat_after.search(s) or pat_before.search(s): + flagged = False + for m in bold_pat.finditer(s): + start, end = m.span() + if start > 0 and cjk_re.match(s[start - 1]): + flagged = True + break + if end < len(s) and cjk_re.match(s[end]): + flagged = True + break + if flagged: vs.append(Violation( i, 'CJK-bold-no-space', 'Bold adjacent to CJK without space on that side.')) diff --git a/.claude/skills/dify-docs-format-check-en/SKILL.md b/.claude/skills/dify-docs-format-check-en/SKILL.md index 60eeb1cb2..2a56772e5 100644 --- a/.claude/skills/dify-docs-format-check-en/SKILL.md +++ b/.claude/skills/dify-docs-format-check-en/SKILL.md @@ -11,17 +11,17 @@ description: > ## Purpose -Verify changed English documentation against every rule in `writing-guides/formatting-guide.md`. Mechanical rules are enforced by a linter script (`check-format-en.py`); judgment-call rules are checked by reading the file. +Verify English documentation against every rule in `writing-guides/formatting-guide.md`. Mechanical rules are enforced by a linter script (`check-format-en.py`); judgment-call rules are checked by reading the file. ## Before Starting -Detect changed documentation files by combining: +Audit the entire file, not just the diff. Default to files currently under review, detected via: - `git diff --name-only` (unstaged changes in tracked files) - `git diff --cached --name-only` (staged changes) - Untracked files from `git status --porcelain` (lines starting with `??`) -Filter for `.mdx` and `.md` files under `en/`. If no changed files are detected, ask the user which files to check. +Filter for `.mdx` and `.md` files under `en/`. If no files are detected, ask the user which files to check. ## Checks diff --git a/.claude/skills/dify-docs-terminology-check/SKILL.md b/.claude/skills/dify-docs-terminology-check/SKILL.md index ae9be821c..bc0cdbf3b 100644 --- a/.claude/skills/dify-docs-terminology-check/SKILL.md +++ b/.claude/skills/dify-docs-terminology-check/SKILL.md @@ -1,18 +1,19 @@ --- name: dify-docs-terminology-check description: > - Check terminology consistency in changed documentation against the glossary - and codebase UI labels. Use after finalizing a draft, or when the user says - "check terminology", "check terms", "verify glossary", or "terminology audit". + Audit terminology consistency across documentation against the codebase UI + labels and the glossary. Covers full files, not just diffs; excludes env var + docs. Use after finalizing a draft, or when the user says "check + terminology", "check terms", "verify glossary", or "terminology audit". --- # Terminology Consistency Check ## Purpose -Verify that changed documentation uses terms consistently with the glossary -(`writing-guides/glossary.md`) and that bolded UI labels match the Dify -codebase i18n files. +Verify that documentation uses terms consistently with the codebase i18n +(source of truth for UI labels) and the glossary (source of truth for general +terms). Covers the whole file, not just the diff. ## Before Starting @@ -27,14 +28,16 @@ codebase i18n files. git fetch origin && git checkout && git pull origin ``` -2. Detect changed documentation files by combining: - - `git diff --name-only` (unstaged changes in tracked files) - - `git diff --cached --name-only` (staged changes) - - Untracked files from `git status --porcelain` (lines starting with `??`) +2. Determine the audit scope. Default to the whole file(s) currently under + review (not just the diff), plus their zh/ja siblings when they exist. + Expand to a directory or the full docs tree if the user specifies. + Always exclude: + - `en/self-host/configuration/environments.mdx` + - `zh/self-host/configuration/environments.mdx` + - `ja/self-host/configuration/environments.mdx` - Filter for `.mdx` and `.md` files under doc content directories (`en/`, `zh/`, - `ja/`, `writing-guides/`). If no changed files are detected, ask the user - which files to check. + Environment variable names are not UI labels and do not belong in the + terminology check. ## Checks to Perform @@ -42,12 +45,10 @@ codebase i18n files. Read `writing-guides/glossary.md` — General Terms section. -For each changed file, verify: +For each file in scope, verify: -- **English docs**: Terms match the English column. Flag any deviations - (e.g., "sandbox runtime" instead of "sandboxed runtime"). -- **Chinese docs**: Terms match the Chinese column. Flag mismatches - (e.g., 沙箱 instead of 沙盒). +- **English docs**: Terms match the English column. Flag any deviations. +- **Chinese docs**: Terms match the Chinese column. Flag mismatches. - **Japanese docs**: Terms match the Japanese column. Flag mismatches. Skip zh/ja checks if the corresponding translation files don't exist locally @@ -55,41 +56,25 @@ Skip zh/ja checks if the corresponding translation files don't exist locally ### 2. UI Label Consistency -Read `writing-guides/glossary.md` — UI Labels section. +For each file in scope, collect: -For each changed file, find all **bolded terms** (text wrapped in `**...**`). -Cross-reference against the UI Labels tables: +- Every **bolded term** (text wrapped in `**...**`) that refers to a UI element. +- Every section heading (`##`, `###`) that names a product feature. -- The bolded text in English docs must match the English (UI) column. -- The bolded text in Chinese docs must match the Chinese (UI) column. -- The bolded text in Japanese docs must match the Japanese (UI) column. +Use judgment to skip bolds that are pure emphasis (e.g., `**semantically**`). -Not all bolded terms are UI labels — use judgment to distinguish UI references -from emphasis. UI labels typically appear in instructional context ("click -**Publish**", "enable **Agent Mode**"). +Verify every collected term against the codebase i18n as the source of truth: +`web/i18n/en-US/`, `web/i18n/zh-Hans/`, `web/i18n/ja-JP/`. Read files with +`git show :` so you don't need to switch branches. The +glossary (`writing-guides/glossary.md`) is a convenience lookup; the +codebase wins when they disagree. -### 3. Codebase Verification (UI Labels Only) +### 3. Glossary Updates -For any UI label flagged as potentially inconsistent, or for new UI labels -not yet in the glossary, verify against the codebase: - -1. Use `git show :` to read i18n files from the user-specified - branch without switching branches. For example: - `git show feat/support-agent-sandbox:web/i18n/en-US/workflow.json` -2. Search the relevant i18n JSON for the key. -3. Report the actual codebase values. -4. If the glossary is outdated compared to the codebase, flag it. - -### 4. First-Mention Rule (zh/ja Only) - -For Chinese and Japanese docs, check that general terms follow the -first-mention parenthetical rule (defined in the glossary): - -- **Local term is primary**: First mention should be "本地术语（English term）" -- **English term is primary**: First mention should be "English Term（本地术语）" -- **Same across all languages**: No parenthetical needed - -Scope is per document — each page resets. +When the audit surfaces a UI label that is new, renamed, or inconsistent +with the codebase, propose an update to `writing-guides/glossary.md` in the +report. Note that `tools/translate/derive-termbase.py` should be run +afterward so `tools/translate/termbase_i18n.md` stays in sync. ## Output Format @@ -104,14 +89,9 @@ Scope is per document — each page resets. - ⚠️ Line {n}: "{found}" should be "{expected}" per glossary **UI Labels** -- ✅ All bolded UI labels match glossary - OR -- ⚠️ Line {n}: **{label}** — glossary says "{expected}", codebase says "{actual}" - -**First-Mention Rule** (zh/ja only) -- ✅ All terms properly introduced +- ✅ All UI labels (bolded terms and feature section headings) match codebase OR -- ⚠️ Line {n}: "{term}" — missing first-mention parenthetical +- ⚠️ Line {n}: **{label}** — codebase says "{expected}" **Glossary Gaps** - Terms used in docs but missing from glossary: {list} @@ -122,5 +102,5 @@ Scope is per document — each page resets. - Do NOT modify any files. This is a read-only audit. - Report findings to the user for review. -- If the glossary and codebase disagree, report both values and let the user - decide which to update. +- Codebase i18n is the source of truth for UI labels. When the glossary + disagrees, update the glossary. diff --git a/en/use-dify/build/additional-features.mdx b/en/use-dify/build/additional-features.mdx index d5d8188f1..75965e253 100644 --- a/en/use-dify/build/additional-features.mdx +++ b/en/use-dify/build/additional-features.mdx @@ -22,7 +22,7 @@ Dify apps come with optional features you can enable to improve the end-user exp Set an opening message that greets users at the start of each conversation, with optional suggested questions to guide them toward what the app does well. -You can insert variables into the opening message and suggested questions to personalize the experience. +You can insert variables into the opening message and suggested questions to personalize the experience. - In the opening message, type `{` or `/` to insert variables from the picker. @@ -43,18 +43,16 @@ You can insert variables into the opening message and suggested questions to per ## Follow-up -When enabled, the LLM automatically suggests 3 follow-up questions after each response, helping users continue the conversation. This feature is a simple toggle—no additional configuration is needed. +When enabled, follow-up questions are generated after each response to help users continue the conversation. - -Follow-up questions are generated by a separate LLM call using your workspace's system reasoning model (set in **Settings** > **Model Provider** > **Default Model Settings**), not the model configured in your app. - +Click **Settings** to pick the model that generates the questions, or write a custom prompt (up to 1,000 characters) to adjust the number, wording, or length of the questions. ## Text to Speech Convert AI responses to audio. You can configure the language and voice to match your app's audience, and enable **Auto Play** to stream audio automatically as the AI responds. -**Text to Speech** uses your workspace's text-to-speech model (set in **Settings** > **Model Provider** > **Default Model Settings**). +**Text to Speech** uses your workspace's text-to-speech model (set in **Settings** > **Model Provider** > **Default Model Settings**). The feature only appears in the **Features** panel when a default TTS model is configured. @@ -64,7 +62,7 @@ The feature only appears in the **Features** panel when a default TTS model is c Enable voice input for the chat interface. When enabled, your end users can dictate messages instead of typing by clicking the microphone button. -**Speech to Text** uses your workspace's speech-to-text model (set in **Settings** > **Model Provider** > **Default Model Settings**). +**Speech to Text** uses your workspace's speech-to-text model (set in **Settings** > **Model Provider** > **Default Model Settings**). The feature only appears in the **Features** panel when a default STT model is configured. @@ -112,7 +110,7 @@ You can configure the score threshold and the embedding model used for semantic To create and manage your annotations: -- Convert existing conversations into annotations directly from **Debug & Preview** or **Logs** by clicking the **Add Annotation** icon on any LLM response. +- Convert existing conversations into annotations directly from **Debug & Preview** or **Logs** by clicking the **Add annotation** icon on any LLM response. Once a message is annotated, the icon changes to **Edit**, so you can modify the annotation in place. diff --git a/ja/use-dify/build/additional-features.mdx b/ja/use-dify/build/additional-features.mdx index 57dd25baa..07d0f2386 100644 --- a/ja/use-dify/build/additional-features.mdx +++ b/ja/use-dify/build/additional-features.mdx @@ -1,9 +1,9 @@ --- -title: "アプリツールキット" -description: "Dify アプリをより便利にするオプション機能" +title: アプリツールキット +description: Dify アプリをより便利にするオプション機能 --- - ⚠️ このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、[英語版](/en/use-dify/build/additional-features)を参照してください。 + ⚠️ このドキュメントは AI によって自動翻訳されています。不正確な部分がある場合は、[英語版](/en/use-dify/build/additional-features) を参照してください。 Dify アプリには、エンドユーザーの体験を向上させるためのオプション機能が用意されています。ビルダーの **機能** パネルを開くと、お使いのアプリタイプで利用可能な機能を確認できます。 @@ -45,28 +45,26 @@ Dify アプリには、エンドユーザーの体験を向上させるための ## フォローアップ -有効にすると、各応答の後に LLM が自動的に 3 つのフォローアップ質問を提案し、ユーザーが会話を続けやすくなります。この機能はシンプルなトグルで、追加の設定は不要です。 +有効にすると、各応答の後にフォローアップ質問が生成され、ユーザーが会話を続けやすくなります。 - -フォローアップ質問は、アプリに設定されたモデルではなく、ワークスペースのシステム推論モデル（**設定** > **モデルプロバイダー** > **デフォルトモデル設定** で設定）を使用した別の LLM 呼び出しによって生成されます。 - +**設定** をクリックすると、質問生成に使うモデルを選んだり、カスタムプロンプト（最大 1,000 文字）で質問の数、表現、長さを調整したりできます。 -## テキスト読み上げ +## テキストから音声へ AI の応答を音声に変換します。アプリの対象ユーザーに合わせて言語と音声を設定でき、**自動再生** を有効にすると AI の応答に合わせて自動的に音声がストリーミングされます。 -**テキスト読み上げ** は、ワークスペースのテキスト読み上げモデル（**設定** > **モデルプロバイダー** > **デフォルトモデル設定** で設定）を使用します。 +**テキストから音声へ** は、ワークスペースのテキスト読み上げモデルを使用します。モデルは **設定** > **モデルプロバイダー** > **デフォルトモデル設定** で指定できます。 デフォルトの TTS モデルが設定されている場合にのみ、**機能** パネルに表示されます。 -## 音声入力 +## 音声からテキストへ チャットインターフェースの音声入力を有効にします。有効にすると、エンドユーザーはマイクボタンをクリックして、タイピングの代わりに音声でメッセージを入力できます。 -**音声入力** は、ワークスペースの音声テキスト変換モデル（**設定** > **モデルプロバイダー** > **デフォルトモデル設定** で設定）を使用します。 +**音声からテキストへ** は、ワークスペースの音声テキスト変換モデルを使用します。モデルは **設定** > **モデルプロバイダー** > **デフォルトモデル設定** で指定できます。 デフォルトの STT モデルが設定されている場合にのみ、**機能** パネルに表示されます。 @@ -83,7 +81,7 @@ AI の応答を音声に変換します。アプリの対象ユーザーに合 - `UPLOAD_AUDIO_FILE_SIZE_LIMIT`（デフォルト： 50 MB） - `UPLOAD_VIDEO_FILE_SIZE_LIMIT`（デフォルト： 100 MB） -詳細は[環境変数](/ja/self-host/configuration/environments)を参照してください。 +詳細は [環境変数](/ja/self-host/configuration/environments) を参照してください。 ## 引用と帰属 @@ -98,23 +96,23 @@ AI の応答の背後にあるソースドキュメントを表示します。 ユーザー入力、AI 出力、またはその両方に含まれる不適切なコンテンツをフィルタリングします。ニーズに応じてモデレーションプロバイダーを選択できます。 -- **OpenAI Moderation**： OpenAI の専用モデレーションモデルを使用して、複数のカテゴリにわたる有害コンテンツを検出します。 +- **OpenAI モデレーション**： OpenAI の専用モデレーションモデルを使用して、複数のカテゴリにわたる有害コンテンツを検出します。 -- **Keywords**： ブロックする用語のリストを定義します。一致するものがあると、プリセット応答がトリガーされます。 +- **キーワード**： ブロックする用語のリストを定義します。一致するものがあると、プリセット応答がトリガーされます。 -- **API Extension**： カスタムモデレーションエンドポイントに接続して、独自のフィルタリングロジックを適用します。 +- **API 拡張**： カスタムモデレーションエンドポイントに接続して、独自のフィルタリングロジックを適用します。 コンテンツがフラグ付けされると、アプリはそのコンテンツを事前に定義したプリセット応答に置き換えます。 ## アノテーション返信 -LLM の応答よりも優先されるキュレーション済みの Q&A ペアを定義します。ユーザーのクエリがスコアしきい値（クエリの一致度）を超えてアノテーションと **意味的に** 一致した場合、LLM を呼び出さずにキュレーション済みの回答が直接返されます。 +LLM の応答よりも優先されるキュレーション済みの Q&A ペアを定義します。ユーザーのクエリがアノテーションと **意味的に** 一致し、スコアしきい値（クエリの一致度）を超えると、LLM を呼び出さずに回答が返されます。 スコアしきい値と意味的マッチングに使用する埋め込みモデルを設定できます。 アノテーションの作成と管理方法は以下のとおりです。 -- **デバッグとプレビュー** または **ログ** から、任意の LLM 応答の **注釈を追加** アイコンをクリックして、既存の会話をアノテーションに変換できます。 +- 任意の LLM 応答の **注釈を追加** アイコンをクリックすると、その会話をアノテーションに変換できます。このアイコンは **デバッグとプレビュー** または **ログ** から利用できます。 メッセージにアノテーションが追加されると、アイコンが **編集** に変わり、その場でアノテーションを修正できます。 diff --git a/tools/translate/formatting-zh.md b/tools/translate/formatting-zh.md index 3ed0ebfdb..b093ac60c 100644 --- a/tools/translate/formatting-zh.md +++ b/tools/translate/formatting-zh.md @@ -145,7 +145,7 @@ Keep the disclaimer regardless of whether the page has been human-reviewed. The These elements must be translated, not left in English: -- **Tab titles:** `` values must use the Chinese UI label from the glossary. +- **Tab titles:** Translate `` values. If the tab title contains a UI label, use the official Chinese UI label. - **Frame captions and image alt text:** Translate both `` and `![alt text]`. - **Bold UI labels:** When a UI label appears in **bold**, use the official Chinese translation from `web/i18n/zh-Hans/`. Refer to the glossary. - **Prompt examples:** Translate natural language text inside code blocks. Keep variable placeholders (`{{variable_name}}`) unchanged. diff --git a/writing-guides/index.md b/writing-guides/index.md index a2ebfc782..868a4c33e 100644 --- a/writing-guides/index.md +++ b/writing-guides/index.md @@ -26,7 +26,7 @@ After completing a writing task, run these checks in order. Each is a self-conta | 3 | dify-docs-terminology-check | Verify terminology consistency against the glossary and codebase UI labels. | | 4 | dify-docs-reader-test | Read each page from a first-time reader's perspective and flag comprehension gaps. | -Steps 1 and 3 apply to any English doc change. Step 2 applies after the zh/ja translations are produced. Step 4 is always the last step because it depends on the others passing. +Steps 1 and 3 apply to any English doc change. Step 2 applies after the zh/ja translations are produced. Steps 1, 2, and 3 audit the whole document, not just the diff. Step 4 is always the last step because it depends on the others passing. ## Reference Files diff --git a/zh/use-dify/build/additional-features.mdx b/zh/use-dify/build/additional-features.mdx index b2ec08989..4b83696c5 100644 --- a/zh/use-dify/build/additional-features.mdx +++ b/zh/use-dify/build/additional-features.mdx @@ -1,6 +1,6 @@ --- -title: "应用工具箱" -description: "让 Dify 应用更实用的可选功能" +title: 应用工具箱 +description: 让 Dify 应用更实用的可选功能 --- ⚠️ 本文档由 AI 自动翻译。如有任何不准确之处，请参考 [英文原版](/en/use-dify/build/additional-features)。 @@ -43,30 +43,28 @@ Dify 应用内置了多项可选功能，开启后可提升终端用户的使用 -## 追问 +## 下一步问题建议 -开启后，LLM 会在每次回复后自动建议 3 个追问问题，帮助用户继续对话。此功能只需简单开关，无需额外配置。 +开启后，每次回复后系统会推荐下一步问题，帮助用户继续对话。 - -追问问题由一次独立的 LLM 调用生成，使用的是工作区的系统推理模型（在 **设置** > **模型供应商** > **默认模型设置** 中配置），而非应用中配置的模型。 - +点击 **设置** 可选择用于生成问题的模型，或编写自定义提示词（最多 1,000 字符）来调整问题的数量、措辞或长度。 -## 文本转语音 +## 文字转语音 将 AI 回复转换为音频。你可以配置语言和语音以适配目标用户，并开启 **自动播放** 功能，在 AI 回复时自动播放音频流。 -**文本转语音** 使用工作区的文本转语音（Text to Speech, TTS）模型（在 **设置** > **模型供应商** > **默认模型设置** 中配置）。 +**文字转语音** 使用工作区的文本转语音（Text to Speech, TTS）模型（在 **设置** > **模型供应商** > **默认模型设置** 中配置）。 只有在配置了默认 TTS 模型后，该功能才会出现在 **功能** 面板中。 -## 语音转文本 +## 语音转文字 为聊天界面启用语音输入。开启后，终端用户可以点击麦克风按钮，通过语音输入消息，无需手动输入。 -**语音转文本** 使用工作区的语音转文本（Speech to Text, STT）模型（在 **设置** > **模型供应商** > **默认模型设置** 中配置）。 +**语音转文字** 使用工作区的语音转文本（Speech to Text, STT）模型（在 **设置** > **模型供应商** > **默认模型设置** 中配置）。 只有在配置了默认 STT 模型后，该功能才会出现在 **功能** 面板中。 @@ -122,7 +120,7 @@ Dify 应用内置了多项可选功能，开启后可提升终端用户的使用 ![添加标注图标](/images/use-dify/workflow/add-annotation-icon.png) -- 在 **日志与标注** > **标注** 选项卡中，可以手动添加新的问答对、管理现有标注并查看命中记录。点击 `...` 进行批量导入或批量导出。 +- 在 **日志与标注** > **标注管理** 选项卡中，可以手动添加新的问答对、管理现有标注并查看命中记录。点击 `...` 进行批量导入或批量导出。 ![批量标注操作](/images/use-dify/workflow/bulk-annotation-operation.png)