dify-docs-terminology-check

name	dify-docs-terminology-check
description	Audit terminology consistency across documentation against the codebase UI labels and the glossary — in prose and in the UI strings shown in screenshots. 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

Read-only audit. Verify that documentation terms match the glossary (general terms) and the Dify codebase i18n (UI labels). Covers the whole file, not just the diff. Do NOT modify any files during the audit; report findings and stop.

Step 1 — Read the sources of truth

1. Read writing-guides/glossary.md. Two sections matter here:
   • ## General Terms — standard body-text terms with English/Chinese/Japanese columns.
   • ## UI Labels — product UI strings with an i18n Key column mapping each label to the codebase.
2. Locate the Dify codebase. If it is available as an additional working directory, use it; otherwise ask the user for the local path to their Dify repo.
3. Ask the user: "Which branch in the Dify codebase should I check UI labels against?" (e.g., main, a feature branch). Default to main if they have no preference.

Step 2 — Pin the codebase ref

1. Sync and read the Dify codebase per writing-guides/index.md → "Syncing the Dify codebase safely". Never git checkout or git pull in the Dify tree.
2. Fetch, then resolve the ref once and record it for the report. In the Dify repo:

   git fetch --tags origin
   REF=$(git rev-parse origin/<branch>)
   

   All i18n lookups below use "$REF"; the report cites it (short form, e.g. 61d2ad572a).

Step 3 — Set the scope

1. Default scope: 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 only if the user says so.
2. Skip zh/ja checks for files whose translations don't exist yet.
3. Always exclude (env var names are not UI labels):
   • en/self-host/deploy/configuration/environments.mdx
   • zh/self-host/deploy/configuration/environments.mdx
   • ja/self-host/deploy/configuration/environments.mdx

Step 4 — Extract candidate terms

For each file in scope, in the docs repo:

grep -anoE '\*\*[^*]+\*\*' <file>    # bolded terms, prints line:**term**
grep -anE '^#{2,3} ' <file>          # section headings, prints line:## Heading

The -a flag is required: some legacy zh/ja pages contain stray NUL bytes, and without it grep prints only Binary file … matches and silently drops the term inventory.

Every bolded term and every heading is a candidate. Step 5 decides deterministically which are UI labels; do not pre-filter by intuition.

Screenshots are candidates too:

grep -anoE '/images/[^) "]+' <file>  # local images, prints line:/images/path

View each listed image and read every UI string it displays; strings that are labels verify under Step 5 like bolded terms. An image showing a superseded string is a finding for re-capture — the fix is a new screenshot at the same path, never a prose edit. The pattern deliberately matches only local /images/ paths; legacy CDN images (assets-docs.dify.ai) stay out of scope.

Step 5 — Classify and verify UI labels against codebase i18n

The codebase i18n is the source of truth for UI labels: web/i18n/en-US/ (flat JSON files with dot-flattened keys, e.g. "menus.apps": "Studio"), plus zh-Hans/ and ja-JP/ siblings. The glossary's i18n Key column maps to them: common.menus.apps → file common.json, key "menus.apps".

A key's value counts as the visible label only after checking its render site: git grep the key under web/ and confirm it lands in on-screen text. Values feeding aria-label, tooltips, or placeholders are not the label, and shared generic keys (common.operation.*) often supply the visible text instead — the Skills section's add button renders operation.add ("Add") while skills.add ("Add skill") is its aria-label. A product or staging screenshot outranks any code inference.

For each candidate term (use the English term; for zh/ja files, take the candidate from the same position in the en sibling):

1. If the term has a ## UI Labels row in the glossary, read its i18n Key; skip to substep 3 to confirm the codebase still agrees.
2. Otherwise search the en-US i18n values. In the Dify repo:

   git grep -nF '"<Term>"' "$REF" -- 'web/i18n/en-US/*.json'
   

   • Exact-value hit (e.g., <REF>:web/i18n/en-US/common.json:285: "menus.apps": "Studio",) → it is a UI label; note the file and key.
   • Multiple exact hits → the value is shared by several keys; pick by tracing which component the documented surface renders (git grep -nF '<key>' "$REF" -- 'web/app/**'; components may reference the key without its file prefix, so retry with the suffix when there are no hits), and record which key you chose and why. Never assume the closest-looking key.
   • No hit → retry case-insensitively: git grep -inF '<term>' "$REF" -- 'web/i18n/en-US/*.json'. A hit here means the doc's casing or wording deviates from the UI string — flag it.
   • Still no hit → not a UI label. Headings fall out of scope here; bolded terms go to Step 6 (general terms) instead.
3. Confirm the exact string at the key:

   git grep -nF '"<key>"' "$REF" -- web/i18n/en-US/<file>.json
   

   The doc's English term must match the printed value exactly (casing included). If the glossary row disagrees with the codebase, the codebase wins — record a glossary gap.
4. For zh/ja siblings, look up the same key in the matching locale:

   git grep -nF '"<key>"' "$REF" -- web/i18n/zh-Hans/<file>.json
   git grep -nF '"<key>"' "$REF" -- web/i18n/ja-JP/<file>.json
   

   Each prints one line with the localized string; the zh/ja doc's bolded term must match it exactly.

Step 6 — Check general terms against the glossary

For candidates that are not UI labels, and for terms noticed while reading the prose:

1. Find the term's row: grep -in '<term>' writing-guides/glossary.md. Expected output: the table row(s) containing the term; no hit means the term is not standardized (consider it for Glossary Gaps if it recurs).
2. Verify the file's usage against the column for its language — English column for en/, Chinese for zh/, Japanese for ja/. Honor the row's Notes (casing rules, context restrictions). Flag every deviation with its line number.

Step 7 — Report

Report findings in this format, then STOP. Do not edit any file until the user responds.

## Terminology Check Results

Checked against Dify codebase `origin/<branch>` at `<short REF>`.

### File: {path}

**General Terms**
- ✅ No issues found
  OR
- ⚠️ Line {n}: "{found}" should be "{expected}" per glossary

**UI Labels**
- ✅ All UI labels (bolded terms and feature section headings) match codebase
  OR
- ⚠️ Line {n}: **{label}** — codebase says "{expected}" (web/i18n/<locale>/<file>.json, key "<key>")

**Stale Screenshots**
- ✅ No local image shows a superseded UI string
  OR
- ⚠️ {image path} (line {n}): shows "{old string}"; the current label is "{new label}" (key "<key>") — re-capture needed

**Glossary Gaps**
- Terms used in docs but missing from glossary: {list}
- Glossary entries outdated compared to codebase: {list}

Step 8 — Glossary updates (only after user approval)

If the user approves fixes for Glossary Gaps:

1. Edit writing-guides/glossary.md with the approved rows.
2. Regenerate the termbase. In the docs repo:

   python3 tools/translate/derive-termbase.py
   

   Must print Generated .../tools/translate/termbase_i18n.md.
3. Verify sync:

   python3 tools/translate/derive-termbase.py --check
   

   Must print termbase_i18n.md is in sync with glossary.md. and exit 0. git diff tools/translate/termbase_i18n.md must show only rows corresponding to the approved glossary edits.