fix(ux): customer-facing copy audit — hide implementation boundaries, add next-action guidance

apps/desktop/src/App.localized-source-error.test.tsx

@@ -0,0 +1,48 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { App } from "./App";
+
+// App mounts the Score surface, whose pdf.js bridge depends on browser canvas
+// globals such as DOMMatrix that jsdom does not provide. This regression only
+// exercises source-selection localization, so isolate that unrelated boundary
+// exactly as the canonical App suite does.
+vi.mock("./features/score/pdfjs", () => ({
+  configureScorePdfWorker: vi.fn(),
+  loadScorePdf: vi.fn(() => ({
+    promise: Promise.resolve({ numPages: 1, getPage: vi.fn() }),
+    destroy: vi.fn(() => Promise.resolve())
+  }))
+}));
+
+const originalLanguage = navigator.language;
+const originalInternals = window.__TAURI_INTERNALS__;
+const originalInvoke = window.__TAURI_INVOKE__;
+
+function setNavigatorLanguage(language: string) {
+  Object.defineProperty(navigator, "language", {
+    configurable: true,
+    value: language
+  });
+}
+
+describe("App localized source errors", () => {
+  afterEach(() => {
+    setNavigatorLanguage(originalLanguage);
+    window.__TAURI_INTERNALS__ = originalInternals;
+    window.__TAURI_INVOKE__ = originalInvoke;
+  });
+
+  it("keeps the browser local-audio fallback in the selected Korean locale", async () => {
+    setNavigatorLanguage("ko-KR");
+    window.__TAURI_INTERNALS__ = undefined;
+    window.__TAURI_INVOKE__ = undefined;
+
+    render(<App />);
+    fireEvent.click(screen.getByRole("button", { name: "로컬 오디오 선택" }));
+
+    expect(await screen.findByRole("alert")).toHaveTextContent(
+      "분석을 시작하려면 WAV, MP3, FLAC 또는 M4A 파일을 선택하세요."
+    );
+    expect(screen.queryByText("Choose a WAV, MP3, FLAC, or M4A file to start analysis.")).toBeNull();
+  });
+});

apps/desktop/src/App.test.tsx

@@ -299,7 +299,7 @@ describe("App", () => {
       expect(screen.getByText(/Song Timeline/i)).toBeTruthy();
     });
     expect(screen.getByText(/Roles & Harmony/i)).toBeTruthy();
-    expect(screen.getByText(/Stems/i)).toBeTruthy();
+    expect(screen.getByText("Stems")).toBeTruthy();
     expect(screen.getByText(/Rehearsal Priorities/i)).toBeTruthy();
     expect(screen.getByText(/Export Cue Sheet/i)).toBeTruthy();
   });
@@ -453,16 +453,17 @@ describe("App", () => {
     expect(screen.queryByText(/analysis failed during execution/i)).toBeNull();
   });
 
-  it("preserves safe file-read failure copy from the intake bridge", async () => {
+  it("localizes safe file-read failure copy from the intake bridge", async () => {
     tauriInvoke.mockRejectedValueOnce(new Error("Could not read the selected audio file."));
 
     render(<App />);
 
     fireEvent.click(screen.getByRole("button", { name: /choose local audio/i }));
 
     await waitFor(() => {
-      expect(screen.getByText(/could not read the selected audio file/i)).toBeTruthy();
+      expect(screen.getByText(/selected audio file could not be read.*choose the file again/i)).toBeTruthy();
     });
+    expect(screen.queryByText(/^Could not read the selected audio file\.$/i)).toBeNull();
     expect(screen.queryByText(/analysis failed during execution/i)).toBeNull();
   });
 
@@ -644,7 +645,7 @@ describe("App", () => {
     await waitFor(() => {
       expect(screen.getByRole("alert").textContent).toMatch(/analysis could not start/i);
     });
-    expect(screen.getAllByRole("status").some((status) => /analysis failed during execution/i.test(status.textContent ?? ""))).toBe(true);
+    expect(screen.getAllByRole("status").some((status) => /stopped partway through/i.test(status.textContent ?? ""))).toBe(true);
   });
 
   it("holds a terminal progress value immediately for pushed failed statuses", async () => {
@@ -1150,7 +1151,7 @@ describe("App", () => {
     expect(input).not.toHaveAttribute("aria-describedby");
   });
 
-  it("handles YouTube import failure with a message", async () => {
+  it("redacts bridge detail when YouTube import fails after URL admission", async () => {
     tauriInvoke.mockRejectedValueOnce(new Error("This video is age restricted."));
 
     render(<App />);
@@ -1163,14 +1164,15 @@ describe("App", () => {
 
     await waitFor(() => {
       const alert = screen.getByRole("alert");
-      expect(alert).toHaveTextContent(/This video is age restricted/i);
+      expect(alert).toHaveTextContent(/Failed to import YouTube URL/i);
+      expect(alert).not.toHaveTextContent(/This video is age restricted/i);
       expect(alert).toHaveAttribute("id", "selection-error");
       expect(input).toHaveAttribute("aria-invalid", "true");
       expect(input).toHaveAttribute("aria-describedby", alert.id);
     });
   });
 
-  it("handles generic exception during YouTube import", async () => {
+  it("redacts generic bridge exceptions during YouTube import", async () => {
     tauriInvoke.mockRejectedValueOnce(new Error("Network Error"));
 
     render(<App />);
@@ -1182,7 +1184,9 @@ describe("App", () => {
     fireEvent.click(button);
 
     await waitFor(() => {
-      expect(screen.getByText(/Network Error/i)).toBeTruthy();
+      const alert = screen.getByRole("alert");
+      expect(alert).toHaveTextContent(/Failed to import YouTube URL/i);
+      expect(alert).not.toHaveTextContent(/Network Error/i);
     });
   });
 

apps/desktop/src/App.tsx

@@ -210,6 +210,11 @@ function sectionCountDetail(t: ReturnType<typeof createTranslator>, sectionCount
 function ConfidenceMetric({ song, t }: { song: RehearsalSong | null; t: ReturnType<typeof createTranslator> }) {
   const sectionCount = song?.sections.length ?? 0;
   const confidenceOrder = { high: 3, medium: 2, low: 1 } as const;
+  const confidenceShortKeys = {
+    low: "confidenceShortLow",
+    medium: "confidenceShortMedium",
+    high: "confidenceShortHigh"
+  } as const satisfies Record<RehearsalSong["sections"][number]["confidence"]["level"], TranslationKey>;
 
   // Performance: Avoid O(N) array scan with .reduce() to find minimum confidence.
   // Instead use a for loop that can early exit (O(K)) as soon as the lowest bound ("low") is hit.
@@ -224,7 +229,7 @@ function ConfidenceMetric({ song, t }: { song: RehearsalSong | null; t: ReturnTy
       }
     }
   }
-  const confidence = lowestConfidence ? `${lowestConfidence[0].toUpperCase()}${lowestConfidence.slice(1)}` : t("metricConfidenceReady");
+  const confidence = lowestConfidence ? t(confidenceShortKeys[lowestConfidence]) : t("metricConfidenceReady");
   const detail = sectionCountDetail(t, sectionCount);
 
   return (
@@ -435,13 +440,13 @@ export function App() {
     setSelectionErrorSource(null);
     const normalizedUrl = youtubeUrl.trim();
     if (!normalizedUrl) {
-      setSelectionError(t("youtubeImportFailed"));
+      setSelectionError(t("youtubeLinkGuidance"));
       setSelectionErrorSource("youtube");
       return;
     }
 
     if (!isSupportedYoutubeUrl(normalizedUrl)) {
-      setSelectionError(t("youtubeImportFailed"));
+      setSelectionError(t("youtubeLinkGuidance"));
       setSelectionErrorSource("youtube");
       return;
     }

apps/desktop/src/App.youtube-url-guidance.test.tsx

@@ -0,0 +1,48 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { App } from "./App";
+
+// App mounts the Score surface, whose pdf.js bridge depends on browser canvas
+// globals such as DOMMatrix that jsdom does not provide. This regression only
+// exercises pre-network YouTube URL admission guidance.
+vi.mock("./features/score/pdfjs", () => ({
+  configureScorePdfWorker: vi.fn(),
+  loadScorePdf: vi.fn(() => ({
+    promise: Promise.resolve({ numPages: 1, getPage: vi.fn() }),
+    destroy: vi.fn(() => Promise.resolve())
+  }))
+}));
+
+const originalLanguage = navigator.language;
+const originalInternals = window.__TAURI_INTERNALS__;
+const originalInvoke = window.__TAURI_INVOKE__;
+
+function setNavigatorLanguage(language: string) {
+  Object.defineProperty(navigator, "language", {
+    configurable: true,
+    value: language
+  });
+}
+
+describe("App YouTube URL admission guidance", () => {
+  afterEach(() => {
+    setNavigatorLanguage(originalLanguage);
+    window.__TAURI_INTERNALS__ = originalInternals;
+    window.__TAURI_INVOKE__ = originalInvoke;
+  });
+
+  it("uses format guidance for a URL rejected before any import attempt", async () => {
+    setNavigatorLanguage("en-US");
+    window.__TAURI_INTERNALS__ = undefined;
+    window.__TAURI_INVOKE__ = undefined;
+
+    render(<App />);
+    const input = screen.getByRole("textbox", { name: /YouTube URL/i });
+    fireEvent.change(input, { target: { value: "https://example.com/watch?v=abc123DEF45" } });
+    fireEvent.click(screen.getByRole("button", { name: /Import YouTube/i }));
+
+    const alert = await screen.findByRole("alert");
+    expect(alert).toHaveTextContent("Use a standard YouTube video link (youtube.com/watch or youtu.be).");
+    expect(alert).not.toHaveTextContent(/check your connection/i);
+  });
+});

apps/desktop/src/features/score/ScoreView.test.tsx

@@ -33,6 +33,8 @@ vi.mock("../../i18n", () => ({
       scoreAttachFailed: "Could not attach the score PDF.",
       scoreReadFailed: "Could not open the score PDF.",
       scoreRemoveFailed: "Could not remove the score PDF.",
+      scoreDesktopOnly: "Score PDFs are only available in the desktop app.",
+      scoreInvalidResponse: "The score could not be prepared. Try adding it again.",
       scoreRequiresProject: "Scores attach to the active analysis project."
     })[key] ?? key,
   detectPreferredLocale: () => "en"
@@ -153,7 +155,7 @@ describe("ScoreView", () => {
 
     fireEvent.click(screen.getByRole("button", { name: "Add score" }));
 
-    expect(await screen.findByRole("alert")).toHaveTextContent("Invalid score bridge response");
+    expect(await screen.findByRole("alert")).toHaveTextContent("The score could not be prepared. Try adding it again.");
   });
 
   it("opens an existing attachment through the read command", async () => {
@@ -216,7 +218,7 @@ describe("ScoreView", () => {
     fireEvent.click(screen.getByRole("button", { name: "Open score: opener.pdf" }));
 
     expect(await screen.findByRole("alert")).toHaveTextContent(
-      "Could not open the score PDF. Invalid score bridge response"
+      "Could not open the score PDF. The score could not be prepared. Try adding it again."
     );
   });
 
@@ -289,7 +291,7 @@ describe("ScoreView", () => {
 
     fireEvent.click(screen.getByRole("button", { name: "Remove: opener.pdf" }));
 
-    expect(await screen.findByRole("alert")).toHaveTextContent("Invalid score bridge response");
+    expect(await screen.findByRole("alert")).toHaveTextContent("The score could not be prepared. Try adding it again.");
   });
 
   it("fails closed when no desktop bridge is available", async () => {

apps/desktop/src/features/score/scoreStorage.localized-errors.test.ts

@@ -0,0 +1,41 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { attachScorePdf } from "./scoreStorage";
+
+const originalLanguage = navigator.language;
+const originalInternals = window.__TAURI_INTERNALS__;
+const originalInvoke = window.__TAURI_INVOKE__;
+
+function setNavigatorLanguage(language: string) {
+  Object.defineProperty(navigator, "language", {
+    configurable: true,
+    value: language
+  });
+}
+
+describe("score storage buyer-visible error localization", () => {
+  afterEach(() => {
+    setNavigatorLanguage(originalLanguage);
+    window.__TAURI_INTERNALS__ = originalInternals;
+    window.__TAURI_INVOKE__ = originalInvoke;
+  });
+
+  it("keeps the browser-only score message in Korean", async () => {
+    setNavigatorLanguage("ko-KR");
+    window.__TAURI_INTERNALS__ = undefined;
+    window.__TAURI_INVOKE__ = undefined;
+
+    await expect(attachScorePdf("project-1", "song-1")).rejects.toThrow(
+      "악보 PDF는 BandScope 데스크톱 앱에서만 사용할 수 있습니다."
+    );
+  });
+
+  it("keeps an invalid bridge response in Korean", async () => {
+    setNavigatorLanguage("ko-KR");
+    window.__TAURI_INTERNALS__ = undefined;
+    window.__TAURI_INVOKE__ = async () => ({});
+
+    await expect(attachScorePdf("project-1", "song-1")).rejects.toThrow(
+      "악보를 준비할 수 없습니다. 다시 추가해 주세요."
+    );
+  });
+});

apps/desktop/src/features/score/scoreStorage.ts

@@ -1,5 +1,6 @@
 import { invoke } from "@tauri-apps/api/core";
 import type { ScoreAttachment } from "@bandscope/shared-types";
+import { createTranslator, detectPreferredLocale, type TranslationKey } from "../../i18n";
 
 type TauriInvoke = (command: string, args?: Record<string, unknown>) => Promise<unknown>;
 
@@ -14,8 +15,13 @@ type TauriBridgeWindow = Window & {
  */
 export type ScoreAttachResult = ScoreAttachment & { fileSizeBytes: number };
 
-const BRIDGE_UNAVAILABLE_MESSAGE = "Score PDFs are only available in the desktop app.";
-const INVALID_RESPONSE_MESSAGE = "Invalid score bridge response";
+const BRIDGE_UNAVAILABLE_KEY = "scoreDesktopOnly" satisfies TranslationKey;
+const INVALID_RESPONSE_KEY = "scoreInvalidResponse" satisfies TranslationKey;
+
+/** Resolve a buyer-visible score-storage message in the currently selected locale. */
+function scoreMessage(key: TranslationKey): string {
+  return createTranslator(detectPreferredLocale())(key);
+}
 
 /**
  * Resolve the desktop invoke bridge following the same detection rules as
@@ -41,12 +47,12 @@ function getInvoke(): TauriInvoke | null {
 
 /**
  * Invoke a score storage command on the desktop bridge, failing closed with
- * a stable error when no bridge is available (browser preview builds).
+ * a stable localized error when no bridge is available (browser preview builds).
  */
 async function invokeScoreCommand(command: string, args: Record<string, unknown>): Promise<unknown> {
   const invokeCommand = getInvoke();
   if (!invokeCommand) {
-    throw new Error(BRIDGE_UNAVAILABLE_MESSAGE);
+    throw new Error(scoreMessage(BRIDGE_UNAVAILABLE_KEY));
   }
 
   return invokeCommand(command, args);
@@ -67,7 +73,7 @@ export async function attachScorePdf(projectId: string, songId: string): Promise
     typeof (response as Record<string, unknown>).fileName !== "string" ||
     typeof (response as Record<string, unknown>).fileSizeBytes !== "number"
   ) {
-    throw new Error(INVALID_RESPONSE_MESSAGE);
+    throw new Error(scoreMessage(INVALID_RESPONSE_KEY));
   }
 
   const payload = response as { scoreId: string; fileName: string; fileSizeBytes: number };
@@ -95,7 +101,7 @@ export async function readScorePdf(projectId: string, scoreId: string): Promise<
     return Uint8Array.from(response as number[]);
   }
 
-  throw new Error(INVALID_RESPONSE_MESSAGE);
+  throw new Error(scoreMessage(INVALID_RESPONSE_KEY));
 }
 
 /**
@@ -105,7 +111,7 @@ export async function readScorePdf(projectId: string, scoreId: string): Promise<
 export async function removeScorePdf(projectId: string, scoreId: string): Promise<boolean> {
   const response = await invokeScoreCommand("remove_score_pdf", { projectId, scoreId });
   if (typeof response !== "boolean") {
-    throw new Error(INVALID_RESPONSE_MESSAGE);
+    throw new Error(scoreMessage(INVALID_RESPONSE_KEY));
   }
 
   return response;

apps/desktop/src/features/workspace/ConfidenceBadge.tsx

@@ -32,7 +32,7 @@ export function ConfidenceBadge({ level }: ConfidenceBadgeProps) {
     <Badge
       variant="outline"
       className={`px-1.5 py-0 h-5 text-[0.65rem] font-bold uppercase tracking-wider ${colorClass}`}
-      title={`Confidence: ${level}`}
+      title={`${t("roleConfidence")}: ${label}`}
     >
       {label}
     </Badge>