Dify Docs Terminology Check

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. A term's presence on sibling pages is not evidence either: neighbors drift together, so a word found across the doc set is traced to the UI like any other ("console" appeared on several pages and nowhere in the product). When a term fails, sweep the whole page for every occurrence before reporting; a finding is not done at one instance.

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}

**Dead glossary rows**
- ✅ Every cited i18n key resolves at `<short REF>`
  OR
- ⚠️ {key} (glossary.md:{n}, {section}) — no longer exists; label resolved from the code as "{current label}"

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.