fix(FR-2765): docs site follow-ups — Lablup transliteration, 가/A icon, sort order (#7133)

Resolves #__pending(FR-2765) — Jira: https://lablup.atlassian.net/browse/FR-2765

> Note: GitHub clone of FR-2765 is in flight; this PR description will be amended once the cloned issue number is available.

## Summary

Four small follow-ups from the Frontend Teams thread (2026-04-28). All scoped to the docs site (`packages/backend.ai-docs-toolkit/` + `packages/backend.ai-webui-docs/`); ship as one PR.

### 1. Korean homeIntro: "Lablup" → "래블업"
Jinho Heo's request — use the standard 래블업 transliteration in the Korean home-page intro paragraph. Pure label change in `WEBSITE_LABELS.ko.homeIntro`; other languages unchanged.

### 2. Language switcher icon: 가 / A
Replaces the Lucide `languages` glyph (which read as a generic squiggle and didn't telegraph "Korean ↔ Latin" to the user). The new icon is a 가 / A pair (one Hangul syllable + one Latin uppercase letter), matching the Material Symbols `language_korean_latin` idea.

The glyph outlines are baked in as inline `<path>` data with `fill: currentColor`, generated offline from Noto Sans CJK KR Bold via `fontTools.pens.svgPathPen.SVGPathPen` (U+AC00 + U+0041, font-size 13, baselines (1, 12) and (11, 23) inside a 24×24 viewBox). This avoids depending on the visitor having a CJK font installed and keeps the icon air-gap-safe. The const carries reproducibility notes so future re-tunes stay deterministic.

### 3. Version selector: `next` first
Reorder `versions:` in `docs-toolkit.config.yaml` so the dev/preview `next` channel surfaces at the top of the version `<select>`. Stable-channel readers still see the `(latest)` marker that the switcher attaches to whichever entry carries `latest: true`, so the cue is preserved.

### 4. Language switcher: `ko` first
Reorder `languages:` in `book.config.yaml` so 한국어 surfaces at the top of the language `<select>`. Build iteration order shifts but is output-only — no consumer relies on it.

## Verification

- `pnpm --filter backend.ai-docs-toolkit build` — clean.
- `pnpm --filter backend.ai-docs-toolkit test` — 150/150 pass.
- `bash scripts/verify.sh` — Relay / Lint / Format / TypeScript ✅.
- Local site rebuild + inspection (`pnpm --filter backend.ai-webui-docs serve:web`):
  - `next/ko/index.html` — homeIntro shows "래블업의 분산..."
  - `next/ko/quickstart.html` — language `<select>` order: 한국어 → English → 日本語 → ภาษาไทย; version `<select>` order: next (selected) → 26.4 (latest)
  - Topbar language icon: single `<path>` (no `<text>`, no font dependency)

## Test plan
- [ ] Reviewer can verify on `webui-docs-next.lablup.ai` after merge + Amplify deploy.
- [ ] Confirm 가/A glyph renders with `currentColor` in dark mode.
- [ ] Confirm version `<select>` shows `next` first on every chapter page.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: yomybaby

packages/backend.ai-docs-toolkit/src/config.ts

@@ -441,7 +441,7 @@ export const WEBSITE_LABELS: Record<string, Record<string, string>> = {
     downloadPdfThisVersion: "PDF 다운로드 (이 버전)",
     homeWelcome: "Backend.AI WebUI 사용자 매뉴얼에 오신 것을 환영합니다",
     homeIntro:
-      "Backend.AI WebUI는 Lablup의 분산 AI/ML 컴퓨팅 플랫폼인 Backend.AI를 위한 공식 브라우저 기반 관리 콘솔입니다. 이 매뉴얼은 첫 연산 세션 생성부터 멀티 테넌트 운영까지, 모든 화면과 워크플로우를 단계별로 안내합니다.",
+      "Backend.AI WebUI는 래블업의 분산 AI/ML 컴퓨팅 플랫폼인 Backend.AI를 위한 공식 브라우저 기반 관리 콘솔입니다. 이 매뉴얼은 첫 연산 세션 생성부터 멀티 테넌트 운영까지, 모든 화면과 워크플로우를 단계별로 안내합니다.",
     homeAboutWebUI: "Backend.AI WebUI 소개",
     homeAboutWebUIBody:
       "Backend.AI 클러스터에 접속해 CPU·GPU 위에서 대화형 또는 배치 세션을 실행하고, 팀과 스토리지 폴더를 공유하며, 학습된 모델을 추론 엔드포인트로 서빙하세요. 모든 작업을 브라우저에서 수행할 수 있습니다.",

packages/backend.ai-docs-toolkit/src/website-builder.test.ts

@@ -227,6 +227,59 @@ describe("buildWebPage — FR-2726 surfaces", () => {
     );
   });
 
+  it("renders language <option> entries in the order supplied by peers (FR-2765)", () => {
+    // Surface 한국어 at the top of the language dropdown by feeding peers
+    // in [ko, en, ja, th] order. The renderer must respect that order
+    // verbatim — without this guarantee, reordering `languages:` in
+    // book.config.yaml (the source of truth for peer order) would not
+    // change the user-visible <select> order.
+    const ctx = makeContext();
+    ctx.metadata = {
+      ...ctx.metadata,
+      lang: "ko",
+      availableLanguages: ["ko", "en", "ja", "th"],
+    };
+    ctx.peers = [
+      {
+        lang: "ko",
+        label: "한국어",
+        href: "../ko/dashboard.html",
+        available: true,
+      },
+      {
+        lang: "en",
+        label: "English",
+        href: "../en/dashboard.html",
+        available: true,
+      },
+      {
+        lang: "ja",
+        label: "日本語",
+        href: "../ja/dashboard.html",
+        available: true,
+      },
+      {
+        lang: "th",
+        label: "ภาษาไทย",
+        href: "../th/dashboard.html",
+        available: true,
+      },
+    ];
+    const html = buildWebPage(ctx);
+
+    // Anchor on the topbar's lang-switcher <select> (avoid colliding with
+    // any other <select> rendered downstream, e.g. the version switcher).
+    const selectMatch = html.match(
+      /<select[^>]*class="lang-switcher__select"[\s\S]*?<\/select>/,
+    );
+    assert.ok(selectMatch, "lang-switcher__select not found");
+    const selectHtml = selectMatch[0];
+    const optionLabels = Array.from(
+      selectHtml.matchAll(/<option[^>]*>([^<]+)<\/option>/g),
+    ).map((m) => m[1]);
+    assert.deepEqual(optionLabels, ["한국어", "English", "日本語", "ภาษาไทย"]);
+  });
+
   it("emits the GitHub icon link only when website.repoUrl is set", () => {
     const html = buildWebPage(makeContext());
     assert.match(html, /aria-label="GitHub"/);
@@ -577,13 +630,43 @@ describe("buildWebPage — FR-2733 sidebar version block placement", () => {
     assert.doesNotMatch(html, /class="doc-sidebar-version"/);
     assert.doesNotMatch(html, /id="version-switcher"/);
   });
+
+  it("renders version <option> entries in the order supplied by allLabels (FR-2765)", () => {
+    // Surface `next` at the top of the version dropdown by feeding
+    // allLabels in [next, 26.4] order. The renderer must respect that
+    // order verbatim — without this guarantee, reordering `versions:`
+    // in docs-toolkit.config.yaml (the source of truth for switcher
+    // order) would not change the user-visible <select> order.
+    const ctx = makeVersionedContext();
+    ctx.versionContext = {
+      ...ctx.versionContext!,
+      current: "next",
+      allLabels: ["next", "26.4"],
+      latest: "26.4",
+    };
+    const html = buildWebPage(ctx);
+
+    const selectMatch = html.match(
+      /<select[^>]*id="version-switcher"[\s\S]*?<\/select>/,
+    );
+    assert.ok(selectMatch, "version-switcher <select> not found");
+    const selectHtml = selectMatch[0];
+    const optionLabels = Array.from(
+      selectHtml.matchAll(/<option[^>]*>([^<]+)<\/option>/g),
+    ).map((m) => m[1]);
+    // First option is `next` (no "(latest)" marker — that attaches to
+    // whichever entry is flagged latest); second is `26.4 (latest)`.
+    assert.deepEqual(optionLabels, ["next", "26.4 (latest)"]);
+  });
 });
 
 describe("buildWebPage / buildHomePage — FR-2758 sidebar 'Introduction' entry", () => {
   it("renders an Introduction anchor at the top of the sidebar linking to ./index.html", () => {
     const html = buildWebPage(makeContext());
 
-    const sidebarMatch = html.match(/<aside class="doc-sidebar">[\s\S]*?<\/aside>/);
+    const sidebarMatch = html.match(
+      /<aside class="doc-sidebar">[\s\S]*?<\/aside>/,
+    );
     assert.ok(sidebarMatch, ".doc-sidebar aside not found");
     const sidebarHtml = sidebarMatch[0];
 
@@ -647,10 +730,7 @@ describe("buildWebPage / buildHomePage — FR-2758 sidebar 'Introduction' entry"
     const koCtx = makeContext();
     koCtx.metadata = { ...koCtx.metadata, lang: "ko" };
     const koHtml = buildWebPage(koCtx);
-    assert.match(
-      koHtml,
-      /<span class="doc-sidebar-intro__label">소개<\/span>/,
-    );
+    assert.match(koHtml, /<span class="doc-sidebar-intro__label">소개<\/span>/);
 
     const jaCtx = makeContext();
     jaCtx.metadata = { ...jaCtx.metadata, lang: "ja" };
@@ -663,10 +743,7 @@ describe("buildWebPage / buildHomePage — FR-2758 sidebar 'Introduction' entry"
     const thCtx = makeContext();
     thCtx.metadata = { ...thCtx.metadata, lang: "th" };
     const thHtml = buildWebPage(thCtx);
-    assert.match(
-      thHtml,
-      /<span class="doc-sidebar-intro__label">บทนำ<\/span>/,
-    );
+    assert.match(thHtml, /<span class="doc-sidebar-intro__label">บทนำ<\/span>/);
   });
 });
 

packages/backend.ai-docs-toolkit/src/website-builder.ts

@@ -459,12 +459,27 @@ function sidebarCategoryIconSvg(group: NavGroup): string {
 }
 
 /**
- * Lucide `languages` icon — used to signal the purpose of the topbar
- * language switcher (FR-2737). Inline SVG, currentColor stroke so it
- * inherits the surrounding text color in both light and dark themes.
- * Source: https://lucide.dev/icons/languages
+ * Language-switcher icon (FR-2765). Replaces the previous Lucide
+ * `languages` glyph (which read as a generic "two-character set" for
+ * non-CJK readers and as a generic squiggle for everyone else) with a
+ * 가 / A pair, matching the Material Symbols `language_korean_latin`
+ * idea: one Hangul syllable + one Latin uppercase letter so the
+ * control's purpose is unambiguous to readers who recognize either
+ * script.
+ *
+ * The glyph outlines are baked in as a single `<path>` with `fill:
+ * currentColor`, generated offline from Noto Sans CJK KR Bold via
+ * fontTools. This avoids depending on the visitor's system having a
+ * CJK font available — without it, an SVG `<text>` "가" would fall
+ * back to a tofu box on stripped-down environments. Air-gap safe.
+ *
+ * Path-generation reproducibility: the `d` attribute below was emitted
+ * by `fontTools.pens.svgPathPen.SVGPathPen` from glyphs U+AC00 (가) and
+ * U+0041 (A) at font-size 13, baselines (1, 12) and (11, 23), inside
+ * a 24×24 viewBox. Re-run the conversion if the visual scale or
+ * placement ever changes; do not hand-edit the path.
  */
-const LUCIDE_LANGUAGES_ICON_SVG = `<svg class="lang-switcher__icon" xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m5 8 6 6"/><path d="m4 14 6-6 2-3"/><path d="M2 5h12"/><path d="M7 2h1"/><path d="m22 22-5-10-5 10"/><path d="M14 18h6"/></svg>`;
+const LANGUAGE_SWITCHER_ICON_SVG = `<svg class="lang-switcher__icon" xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true" focusable="false"><path d="M9.22 1.09V13.13H10.96V7.12H12.63V5.71H10.96V1.09ZM2.07 2.34V3.73H5.99C5.69 6.41 4.2 8.31 1.4 9.75L2.38 11.06C6.38 9.05 7.76 5.96 7.76 2.34Z M10.95 23H12.9L13.57 20.53H16.68L17.36 23H19.38L16.3 13.37H14.03ZM13.99 19.04 14.28 17.98C14.56 16.98 14.84 15.89 15.09 14.84H15.15C15.43 15.86 15.69 16.98 15.99 17.98L16.28 19.04Z"/></svg>`;
 
 // Canonical Lucide `rocket` icon. Swapped in (FR-2737) for the
 // hand-drawn placeholder, whose silhouette read as a horizontal blob
@@ -1372,15 +1387,18 @@ function buildBaiTopbar(
   // localization passes through to search.js.
   void noResultsAttr;
 
-  // Lang switcher (FR-2737 — icon-only variant).
+  // Lang switcher (FR-2737 — icon-only variant; icon updated in FR-2765).
   //
-  // The visible affordance is a single Lucide `languages` icon. A
-  // transparent native `<select>` is layered on top of the icon, so
-  // clicking the icon opens the OS-native option list — every browser
-  // and platform (incl. mobile) renders this dropdown using its own
-  // accessible UI. We don't reinvent the menu in JS: keyboard support,
-  // screen-reader announcements, and touch-friendly option pickers all
-  // come "for free" from the native control.
+  // The visible affordance is a single 가 / A pair (Hangul + Latin)
+  // baked in as inline SVG `<path>` data — see
+  // `LANGUAGE_SWITCHER_ICON_SVG` above for the source-font /
+  // glyph-extraction details. A transparent native `<select>` is
+  // layered on top of the icon, so clicking the icon opens the OS-
+  // native option list — every browser and platform (incl. mobile)
+  // renders this dropdown using its own accessible UI. We don't
+  // reinvent the menu in JS: keyboard support, screen-reader
+  // announcements, and touch-friendly option pickers all come "for
+  // free" from the native control.
   //
   // Pages where the chapter is missing in a peer language still get an
   // option, but its value is that language's `index.html` so the click
@@ -1408,7 +1426,7 @@ function buildBaiTopbar(
   // label association.
   const langSwitcherHtml = `<label class="lang-switcher" aria-label="Language switcher">
     <select class="lang-switcher__select" aria-label="Language switcher" onchange="if(this.value)window.location.assign(this.value)">${langOptions}</select>
-    ${LUCIDE_LANGUAGES_ICON_SVG}
+    ${LANGUAGE_SWITCHER_ICON_SVG}
   </label>`;
 
   // FR-2733: the version selector used to render here in the topbar

packages/backend.ai-webui-docs/docs-toolkit.config.yaml

@@ -39,23 +39,33 @@ pdfMetadata:
 # assets are linked from the per-language landing page (FR-2732).
 #
 # Release procedure (when cutting a new minor X.Y):
-#   1. Insert a new entry ABOVE the `next` entry with
+#   1. Insert a new entry IMMEDIATELY BELOW the `next` entry (above the
+#      previous-latest minor) with
 #        label: "X.Y"
 #        source: { kind: archive-branch, ref: docs-archive/X.Y }
 #        pdfTag: "vX.Y.Z"   # highest patch in the minor
 #   2. Move `latest: true` onto the new entry; remove it from the prior one.
-#   3. Leave the `next` entry last; it never carries `latest: true`.
+#   3. Keep the `next` entry at the TOP of the list (FR-2765 — surfaces
+#      `next` at the top of the version <select>); it never carries
+#      `latest: true`.
 #   See the docs release runbook for the full procedure.
 versions:
+  # FR-2765: `next` is intentionally listed first so it appears at the
+  # top of the version `<select>` dropdown. Readers visiting `next` see
+  # it as the active option without scrolling, and stable-channel
+  # readers still see the "(latest)" marker that the switcher renders
+  # next to whichever entry has `latest: true`. Build iteration follows
+  # this list order, but build order is output-only — no consumer of
+  # the build relies on it.
+  - label: "next"
+    source:
+      kind: workspace
   - label: "26.4"
     source:
       kind: archive-branch
       ref: docs-archive/26.4
     latest: true
     pdfTag: "v26.4.7"
-  - label: "next"
-    source:
-      kind: workspace
 
 # Product name for log messages
 productName: "Backend.AI WebUI Docs"

packages/backend.ai-webui-docs/src/book.config.yaml

@@ -4,10 +4,15 @@ title: |
   User Guide
 description: Multilingual user manual by Lablup Inc.
 type: document
+# FR-2765: ko first so the language switcher surfaces 한국어 at the top
+# of the dropdown. The build pipeline iterates this list to enumerate
+# per-language pages, but iteration order is output-only — no consumer
+# of the build relies on it. Remaining order (en, ja, th) preserved
+# for downstream stability.
 languages:
+  - ko
   - en
   - ja
-  - ko
   - th
 # F3 — Information architecture
 # ----------------------------------------------------------------------------