fix(FR-3021): unify shipped i18n term drift and repair docs-lint terminology parser by yomybaby · Pull Request #7678 · lablup/backend.ai-webui

yomybaby · 2026-06-02T03:04:11Z

Summary

Phase 0 of the terminology / i18n unification effort — quick-win fixes decoupled from tooling. Corrects shipped, user-facing terminology drift and repairs a silently-broken terminology checker, establishing a clean baseline before a machine-readable termbase is introduced in #7737 (stacked on this PR).

Changes

Shipped i18n drift (user-facing):

resources/i18n/*.json: AppProxy → App Proxy in 3 sentence values (ActivePoolDescription, TrafficStatusTooltip, replicaStatus.tooltip.Healthy) across all 21 locales (FR-2841 convention). The English fix landed first; the 60 cross-locale fixes were added in review after Copilot caught that the other 20 locales still shipped AppProxy. The AppProxy* i18n keys are identifiers and stay unchanged.
resources/i18n/en.json: fix the "Project": "Proejct" typo.
resources/i18n/en.json: fix "Projects": "Project" (plural key mapped to a singular value → "Projects").
resources/i18n/ko.json: 리소스 그룹 → 자원 그룹 in 4 values (TERMINOLOGY.md fixes the canonical Korean term as 자원 그룹). Standalone 리소스 / 리소스 프리셋 are left unchanged.

Tooling:

.claude/agents/docs-lint.md: repair the ## Terms to Avoid extraction. The previous awk '/^## Terms to Avoid/,/^## /' returned only the header line — because that section is the last ## block, the range end-pattern matched its own opening line and closed immediately, yielding zero table rows and silently disabling the docs terminology check. Replaced with a flag-based extraction that reads to EOF. (Stacked feat(FR-3048): machine-readable terminology.json single source of truth + i18n terminology checker #7737 supersedes this by reading terminology.json directly.)
CLAUDE.md / AGENTS.md: repoint dangling on-demand skill references to the real fw-plugin skills — i18n-guide → i18n-patterns, docs-guide → docs-writing-guide, storybook-guide → storybook-patterns. (CLAUDE.md is a symlink to AGENTS.md, so a single edit updates both.)

Verification

prettier --check clean on the changed files; eslint --max-warnings=0 (i18n json-schema-validator) passes on all touched locales.
Edits are value-only (no key add/remove/reorder), so key parity across locales is untouched and no translation propagation is needed.

🤖 Generated with Claude Code

yomybaby · 2026-06-02T03:04:27Z

How to use the Graphite Merge Queue

Add either label to this PR to merge it via the merge queue:

flow:merge-queue - adds this PR to the back of the merge queue
flow:hotfix - for urgent changes, fast-track this PR to the front of the merge queue

You must have a Graphite account in order to use the merge queue. Sign up using this link.

_{An organization admin has required the Graphite Merge Queue in this repository.} _{Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue.}

This stack of pull requests is managed by Graphite. Learn more about stacking.

Copilot

Pull request overview

This PR focuses on standardizing user-facing terminology in shipped i18n strings (notably “App Proxy” and Korean “자원 그룹”), and updating agent documentation to make the docs-lint terminology extraction guidance more robust.

Changes:

Adjusts Korean/English translations to reduce term drift (e.g., “Resource Group” wording in ko, pluralization fixes, “App Proxy” spacing in en).
Updates AGENTS.md to rename referenced on-demand guidance items.
Repairs docs-lint documentation to use a safer awk snippet when extracting the “## Terms to Avoid” section from TERMINOLOGY.md.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 7 comments.

File	Description
`resources/i18n/ko.json`	Korean terminology tweaks (e.g., “자원 그룹”) to reduce drift.
`resources/i18n/en.json`	English terminology fixes (pluralization, typo) and “App Proxy” spelling in deployment/replica tooltips.
`AGENTS.md`	Updates the names of referenced on-demand skills/guides and i18n guidance note.
`.claude/agents/docs-lint.md`	Improves the documented `awk` approach for extracting “Terms to Avoid” reliably.

…th + i18n terminology checker Phase 1+2 of the terminology unification effort (stacked on #7678 / FR-3021). - terminology.json (+ terminology.schema.json): machine-readable termbase — 39 concepts (Core/Feature/User Roles/UI Nav) with per-language preferred terms (en/ko/ja/th), context qualifiers, decidingFR, conceptId links; 9 avoid rows. - generate-terminology.mjs: dependency-free generator that renders the term tables + Terms-to-Avoid table into TERMINOLOGY.md between  markers (human prose preserved). --check mode for CI. Wired as build:terminology / check:terminology-md. - TERMINOLOGY.md restructured into generated Standardized Terms + human Concept Notes + generated Terms to Avoid. No prose lost. - docs-lint.md + docs-update-reviewer.md: read terminology.json avoid[] instead of scraping the markdown table — collapses 3 duplicated avoid-lists into 1 source. - check-terminology-i18n.mjs: deterministic, READ-ONLY i18n VALUE terminology checker (CHECK 1) — code-context aware, anaphora-safe compound guard, inline-ignore + allowlist. Wired warn-only into scripts/verify.sh + lint:terminology. CHECK 2 (key->two-values) implemented but OFF by default (--check2 opt-in; too noisy today). No new npm dependency (native Node ESM). bash scripts/verify.sh => ALL PASS; checker is read-only. Resolves #7736 (FR-3048) Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

graphite-app · 2026-06-05T03:31:52Z

Merge activity

Jun 5, 3:31 AM UTC: yomybaby added this pull request to the Graphite merge queue.
Jun 5, 3:35 AM UTC: The Graphite merge queue couldn't merge this PR because it was not satisfying all requirements (PR does not have required approvals).
Jun 5, 3:55 AM UTC: yomybaby added this pull request to the Graphite merge queue.
Jun 5, 3:58 AM UTC: Merged by the Graphite merge queue.

…inology parser (#7678) Resolves #7677 (FR-3021) ## Summary Phase 0 of the terminology / i18n unification effort — quick-win fixes decoupled from tooling. Corrects shipped, user-facing terminology drift and repairs a silently-broken terminology checker, establishing a clean baseline before a machine-readable termbase is introduced in #7737 (stacked on this PR). ## Changes **Shipped i18n drift (user-facing):** - `resources/i18n/*.json`: `AppProxy` → `App Proxy` in 3 sentence values (`ActivePoolDescription`, `TrafficStatusTooltip`, `replicaStatus.tooltip.Healthy`) across **all 21 locales** (FR-2841 convention). The English fix landed first; the **60 cross-locale fixes were added in review** after Copilot caught that the other 20 locales still shipped `AppProxy`. The `AppProxy*` i18n **keys** are identifiers and stay unchanged. - `resources/i18n/en.json`: fix the `"Project": "Proejct"` typo. - `resources/i18n/en.json`: fix `"Projects": "Project"` (plural key mapped to a singular value → `"Projects"`). - `resources/i18n/ko.json`: `리소스 그룹` → `자원 그룹` in 4 values (TERMINOLOGY.md fixes the canonical Korean term as `자원 그룹`). Standalone `리소스` / `리소스 프리셋` are left unchanged. **Tooling:** - `.claude/agents/docs-lint.md`: repair the `## Terms to Avoid` extraction. The previous `awk '/^## Terms to Avoid/,/^## /'` returned only the header line — because that section is the last `##` block, the range end-pattern matched its own opening line and closed immediately, yielding zero table rows and **silently disabling the docs terminology check**. Replaced with a flag-based extraction that reads to EOF. (Stacked #7737 supersedes this by reading `terminology.json` directly.) - `CLAUDE.md` / `AGENTS.md`: repoint dangling on-demand skill references to the real fw-plugin skills — `i18n-guide` → `i18n-patterns`, `docs-guide` → `docs-writing-guide`, `storybook-guide` → `storybook-patterns`. (`CLAUDE.md` is a symlink to `AGENTS.md`, so a single edit updates both.) ## Verification - `prettier --check` clean on the changed files; `eslint --max-warnings=0` (i18n json-schema-validator) passes on all touched locales. - Edits are **value-only** (no key add/remove/reorder), so key parity across locales is untouched and no translation propagation is needed. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

…th + i18n terminology checker (#7737) Resolves #7736 (FR-3048) > **Stacked on #7678** (Phase 0 — terminology drift + docs-lint awk repair). Review/merge #7678 first. ## Summary Phase 1+2 of the terminology / i18n unification effort. Introduces a **machine-readable single source of truth** for terminology (`terminology.json`) and wires it into the `docs-lint` agent and a new **deterministic i18n terminology checker**, so the user-manual docs and the app i18n stop drifting apart and the AI agents that co-maintain this repo can mechanically consult and enforce one vocabulary. ## Phase 1 — machine-readable single source of truth - **`packages/backend.ai-webui-docs/terminology.json`** (+ `terminology.schema.json`) — 39 concepts (Core Concepts / Feature-Specific / User Roles / UI Navigation) with per-language preferred terms (en/ko/ja/th), `context` qualifiers, `decidingFR`, and `conceptId` links; 9 `avoid[]` rows. - **`packages/backend.ai-webui-docs/scripts/generate-terminology.mjs`** — dependency-free generator that renders the term tables + the Terms-to-Avoid table into `TERMINOLOGY.md` between `` markers. Human prose outside the markers is preserved. `--check` mode fails when the file is stale (CI-friendly). Wired as `build:terminology` / `check:terminology-md`. - **`TERMINOLOGY.md`** restructured into a generated `## Standardized Terms` section + human `## Concept Notes` + a generated `## Terms to Avoid`. No prose lost. - **`.claude/agents/docs-lint.md`** and **`docs-update-reviewer.md`** now read `terminology.json` `avoid[]` instead of scraping the markdown table — collapsing the three previously-duplicated avoid-lists into one source. ## Phase 2 — deterministic i18n terminology gate (warn-only) - **`scripts/check-terminology-i18n.mjs`** — dependency-free, **READ-ONLY** checker that scans i18n **VALUES** (never keys) in `resources/i18n/*.json` + `packages/backend.ai-ui/src/locale/*.json` against `terminology.json` `avoid[]` (CHECK 1). It is code-context aware (skips identifiers / URLs / config keys / `{{interp}}` / backticks), has an anaphora-safe approved-compound guard (so "resource group" never trips the bare "group" rule), and supports an inline `[[i18n-term-ok]]` marker + `scripts/terminology-i18n.allowlist.json`. `--warn` (default, exit 0) / `--strict` (blocks on error-severity). Wired as `lint:terminology` and a **non-blocking warn-only** step in `scripts/verify.sh`. - CHECK 2 (key→two-values divergence) is implemented but **OFF by default** (`--check2` opt-in): its current segment-across-namespace form is too noisy (~3,400 mostly-benign hits). Refining it is a tracked follow-up. ## Verification - `node packages/backend.ai-webui-docs/scripts/generate-terminology.mjs --check` → in sync (exit 0). - `node scripts/check-terminology-i18n.mjs --warn` → **1 genuine warn-only finding** (`error.UserHasNoGroup` uses "group" for "project"); **0 false positives**; `--strict` exits 0. - `bash scripts/verify.sh` → **`=== ALL PASS ===`** (Relay / Lint / Format / TypeScript / warmup); terminology step is warn-only. - **No new npm dependency** (`pnpm-lock.yaml` / `pnpm-workspace.yaml` unchanged); all new scripts are native Node ESM. Checker verified read-only (i18n file mtimes unchanged before/after a run). ## Out of scope (follow-ups) - Flip the i18n terminology gate to **blocking** after triaging warn findings. - Redesign CHECK 2 into a high-signal form (near-duplicate values / termbase-linked segments only). - Extend docs-lint terminology drift to ko/ja/th (Phase 3). - Terminology governance / term-owner + deprecation flow (Phase 4). 🤖 Generated with [Claude Code](https://claude.com/claude-code)

…inology parser (#7678) Resolves #7677 (FR-3021) ## Summary Phase 0 of the terminology / i18n unification effort — quick-win fixes decoupled from tooling. Corrects shipped, user-facing terminology drift and repairs a silently-broken terminology checker, establishing a clean baseline before a machine-readable termbase is introduced in #7737 (stacked on this PR). ## Changes **Shipped i18n drift (user-facing):** - `resources/i18n/*.json`: `AppProxy` → `App Proxy` in 3 sentence values (`ActivePoolDescription`, `TrafficStatusTooltip`, `replicaStatus.tooltip.Healthy`) across **all 21 locales** (FR-2841 convention). The English fix landed first; the **60 cross-locale fixes were added in review** after Copilot caught that the other 20 locales still shipped `AppProxy`. The `AppProxy*` i18n **keys** are identifiers and stay unchanged. - `resources/i18n/en.json`: fix the `"Project": "Proejct"` typo. - `resources/i18n/en.json`: fix `"Projects": "Project"` (plural key mapped to a singular value → `"Projects"`). - `resources/i18n/ko.json`: `리소스 그룹` → `자원 그룹` in 4 values (TERMINOLOGY.md fixes the canonical Korean term as `자원 그룹`). Standalone `리소스` / `리소스 프리셋` are left unchanged. **Tooling:** - `.claude/agents/docs-lint.md`: repair the `## Terms to Avoid` extraction. The previous `awk '/^## Terms to Avoid/,/^## /'` returned only the header line — because that section is the last `##` block, the range end-pattern matched its own opening line and closed immediately, yielding zero table rows and **silently disabling the docs terminology check**. Replaced with a flag-based extraction that reads to EOF. (Stacked #7737 supersedes this by reading `terminology.json` directly.) - `CLAUDE.md` / `AGENTS.md`: repoint dangling on-demand skill references to the real fw-plugin skills — `i18n-guide` → `i18n-patterns`, `docs-guide` → `docs-writing-guide`, `storybook-guide` → `storybook-patterns`. (`CLAUDE.md` is a symlink to `AGENTS.md`, so a single edit updates both.) ## Verification - `prettier --check` clean on the changed files; `eslint --max-warnings=0` (i18n json-schema-validator) passes on all touched locales. - Edits are **value-only** (no key add/remove/reorder), so key parity across locales is untouched and no translation propagation is needed. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

…th + i18n terminology checker (#7737) Resolves #7736 (FR-3048) > **Stacked on #7678** (Phase 0 — terminology drift + docs-lint awk repair). Review/merge #7678 first. ## Summary Phase 1+2 of the terminology / i18n unification effort. Introduces a **machine-readable single source of truth** for terminology (`terminology.json`) and wires it into the `docs-lint` agent and a new **deterministic i18n terminology checker**, so the user-manual docs and the app i18n stop drifting apart and the AI agents that co-maintain this repo can mechanically consult and enforce one vocabulary. ## Phase 1 — machine-readable single source of truth - **`packages/backend.ai-webui-docs/terminology.json`** (+ `terminology.schema.json`) — 39 concepts (Core Concepts / Feature-Specific / User Roles / UI Navigation) with per-language preferred terms (en/ko/ja/th), `context` qualifiers, `decidingFR`, and `conceptId` links; 9 `avoid[]` rows. - **`packages/backend.ai-webui-docs/scripts/generate-terminology.mjs`** — dependency-free generator that renders the term tables + the Terms-to-Avoid table into `TERMINOLOGY.md` between `` markers. Human prose outside the markers is preserved. `--check` mode fails when the file is stale (CI-friendly). Wired as `build:terminology` / `check:terminology-md`. - **`TERMINOLOGY.md`** restructured into a generated `## Standardized Terms` section + human `## Concept Notes` + a generated `## Terms to Avoid`. No prose lost. - **`.claude/agents/docs-lint.md`** and **`docs-update-reviewer.md`** now read `terminology.json` `avoid[]` instead of scraping the markdown table — collapsing the three previously-duplicated avoid-lists into one source. ## Phase 2 — deterministic i18n terminology gate (warn-only) - **`scripts/check-terminology-i18n.mjs`** — dependency-free, **READ-ONLY** checker that scans i18n **VALUES** (never keys) in `resources/i18n/*.json` + `packages/backend.ai-ui/src/locale/*.json` against `terminology.json` `avoid[]` (CHECK 1). It is code-context aware (skips identifiers / URLs / config keys / `{{interp}}` / backticks), has an anaphora-safe approved-compound guard (so "resource group" never trips the bare "group" rule), and supports an inline `[[i18n-term-ok]]` marker + `scripts/terminology-i18n.allowlist.json`. `--warn` (default, exit 0) / `--strict` (blocks on error-severity). Wired as `lint:terminology` and a **non-blocking warn-only** step in `scripts/verify.sh`. - CHECK 2 (key→two-values divergence) is implemented but **OFF by default** (`--check2` opt-in): its current segment-across-namespace form is too noisy (~3,400 mostly-benign hits). Refining it is a tracked follow-up. ## Verification - `node packages/backend.ai-webui-docs/scripts/generate-terminology.mjs --check` → in sync (exit 0). - `node scripts/check-terminology-i18n.mjs --warn` → **1 genuine warn-only finding** (`error.UserHasNoGroup` uses "group" for "project"); **0 false positives**; `--strict` exits 0. - `bash scripts/verify.sh` → **`=== ALL PASS ===`** (Relay / Lint / Format / TypeScript / warmup); terminology step is warn-only. - **No new npm dependency** (`pnpm-lock.yaml` / `pnpm-workspace.yaml` unchanged); all new scripts are native Node ESM. Checker verified read-only (i18n file mtimes unchanged before/after a run). ## Out of scope (follow-ups) - Flip the i18n terminology gate to **blocking** after triaging warn findings. - Redesign CHECK 2 into a high-signal form (near-duplicate values / termbase-linked segments only). - Extend docs-lint terminology drift to ko/ja/th (Phase 3). - Terminology governance / term-owner + deprecation flow (Phase 4). 🤖 Generated with [Claude Code](https://claude.com/claude-code)

Copilot AI review requested due to automatic review settings June 2, 2026 03:04

github-actions Bot assigned yomybaby Jun 2, 2026

github-actions Bot added area:ux UI / UX issue. area:i18n Localization labels Jun 2, 2026

Copilot started reviewing on behalf of yomybaby June 2, 2026 03:04 View session

github-actions Bot added the size:S 10~30 LoC label Jun 2, 2026

Copilot AI reviewed Jun 2, 2026

View reviewed changes

Comment thread AGENTS.md

Comment thread AGENTS.md

Comment thread .claude/agents/docs-lint.md

Comment thread resources/i18n/en.json

Comment thread resources/i18n/en.json

Comment thread resources/i18n/en.json

Comment thread AGENTS.md

This was referenced Jun 4, 2026

Terminology governance: machine-readable terminology.json + generator + docs-lint rewire + deterministic i18n terminology checker (warn) #7736

Closed

feat(FR-3048): machine-readable terminology.json single source of truth + i18n terminology checker #7737

Merged

yomybaby force-pushed the worktree-fr-3021-terminology-phase0 branch from 3b865a5 to 9aa1ae2 Compare June 4, 2026 22:52

github-actions Bot added i18n terminology size:L 100~500 LoC and removed size:S 10~30 LoC labels Jun 4, 2026

graphite-app Bot force-pushed the worktree-fr-3021-terminology-phase0 branch from 9aa1ae2 to 98d71b8 Compare June 5, 2026 03:32

graphite-app Bot force-pushed the worktree-fr-3021-terminology-phase0 branch from 98d71b8 to 934168d Compare June 5, 2026 03:56

graphite-app Bot merged commit 934168d into main Jun 5, 2026
8 checks passed

graphite-app Bot deleted the worktree-fr-3021-terminology-phase0 branch June 5, 2026 03:58

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix(FR-3021): unify shipped i18n term drift and repair docs-lint terminology parser#7678

fix(FR-3021): unify shipped i18n term drift and repair docs-lint terminology parser#7678
graphite-app[bot] merged 1 commit into
mainfrom
worktree-fr-3021-terminology-phase0

yomybaby commented Jun 2, 2026 •

edited

Loading

Uh oh!

yomybaby commented Jun 2, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

graphite-app Bot commented Jun 5, 2026 •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

yomybaby commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Verification

Uh oh!

yomybaby commented Jun 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

How to use the Graphite Merge Queue

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

graphite-app Bot commented Jun 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merge activity

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

yomybaby commented Jun 2, 2026 •

edited

Loading

yomybaby commented Jun 2, 2026 •

edited

Loading

graphite-app Bot commented Jun 5, 2026 •

edited

Loading