Skip to content

🙌 OpenHands: AI-Driven Development

fix(a11y): one Settings main landmark, Customize aria-current, synced html lang (#18012)

Engel Nyst9cbf09d938dd
diff --git a/__tests__/components/features/sidebar/sidebar.test.tsx b/__tests__/components/features/sidebar/sidebar.test.tsx
index b2bfcc3b25..cfe447299e 100644
--- a/__tests__/components/features/sidebar/sidebar.test.tsx
+++ b/__tests__/components/features/sidebar/sidebar.test.tsx
@@ -509,6 +509,29 @@ describe("Sidebar", () => {
);
});
+ it.each(["/customize", "/mcp", "/skills", "/plugins", "/apps"])(
+ "marks the Customize row as the current page on %s",
+ (path) => {
+ renderSidebar(path);
+
+ expect(screen.getByTestId("sidebar-skills-link")).toHaveAttribute(
+ "aria-current",
+ "page",
+ );
+ },
+ );
+
+ it.each(["/conversations", "/automations"])(
+ "does not mark the Customize row as current on %s",
+ (path) => {
+ renderSidebar(path);
+
+ expect(screen.getByTestId("sidebar-skills-link")).not.toHaveAttribute(
+ "aria-current",
+ );
+ },
+ );
+
it("pins and unpins a sidebar page as the home route without navigating", () => {
// Arrange: the mocked active backend is `local` with no org.
const pinKey = getPinnedHomeRouteKey("local", null);
diff --git a/__tests__/components/shared/navigation-link.test.tsx b/__tests__/components/shared/navigation-link.test.tsx
index e8aeec2b13..dda9023f8d 100644
--- a/__tests__/components/shared/navigation-link.test.tsx
+++ b/__tests__/components/shared/navigation-link.test.tsx
@@ -125,4 +125,28 @@ describe("NavigationLink", () => {
"aria-current",
);
});
+
+ it("keeps a caller-supplied aria-current when the path does not match", () => {
+ // A section link (e.g. the sidebar Customize row) is current on routes
+ // other than its own redirecting destination.
+ render(
+ <NavigationProvider
+ value={{
+ currentPath: "/mcp",
+ conversationId: null,
+ isNavigating: false,
+ navigate: vi.fn(),
+ }}
+ >
+ <NavigationLink to="/customize" aria-current="page">
+ Customize
+ </NavigationLink>
+ </NavigationProvider>,
+ );
+
+ expect(screen.getByRole("link", { name: "Customize" })).toHaveAttribute(
+ "aria-current",
+ "page",
+ );
+ });
});
diff --git a/__tests__/hooks/use-sync-document-language.test.ts b/__tests__/hooks/use-sync-document-language.test.ts
new file mode 100644
index 0000000000..ab6745d09f
--- /dev/null
+++ b/__tests__/hooks/use-sync-document-language.test.ts
@@ -0,0 +1,52 @@
+import { act, renderHook } from "@testing-library/react";
+import { createInstance } from "i18next";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { getI18n, setI18n } from "#/i18n";
+import { useSyncDocumentLanguage } from "#/hooks/use-sync-document-language";
+
+// Screen readers pick their voice from <html lang>; right-to-left scripts
+// also need <html dir> (#17909).
+describe("useSyncDocumentLanguage", () => {
+ beforeEach(async () => {
+ const instance = createInstance();
+ await instance.init({ lng: "de", resources: {} });
+ setI18n(instance);
+ document.documentElement.lang = "en";
+ document.documentElement.removeAttribute("dir");
+ });
+
+ afterEach(() => {
+ setI18n(null);
+ document.documentElement.lang = "en";
+ document.documentElement.removeAttribute("dir");
+ });
+
+ it("applies the active language on mount", () => {
+ renderHook(() => useSyncDocumentLanguage());
+
+ expect(document.documentElement.lang).toBe("de");
+ expect(document.documentElement.dir).toBe("ltr");
+ });
+
+ it("follows language changes, setting rtl for Arabic", async () => {
+ renderHook(() => useSyncDocumentLanguage());
+
+ await act(() => getI18n().changeLanguage("ar"));
+ expect(document.documentElement.lang).toBe("ar");
+ expect(document.documentElement.dir).toBe("rtl");
+
+ await act(() => getI18n().changeLanguage("fr"));
+ expect(document.documentElement.lang).toBe("fr");
+ expect(document.documentElement.dir).toBe("ltr");
+ });
+
+ it("stops following language changes after unmount", async () => {
+ const { unmount } = renderHook(() => useSyncDocumentLanguage());
+ unmount();
+
+ await act(() => getI18n().changeLanguage("ar"));
+
+ expect(document.documentElement.lang).toBe("de");
+ expect(document.documentElement.dir).toBe("ltr");
+ });
+});
diff --git a/__tests__/i18n/command-menu-open-label.test.ts b/__tests__/i18n/command-menu-open-label.test.ts
new file mode 100644
index 0000000000..ff39b07700
--- /dev/null
+++ b/__tests__/i18n/command-menu-open-label.test.ts
@@ -0,0 +1,25 @@
+import fs from "fs";
+import path from "path";
+import { describe, expect, it } from "vitest";
+import { AvailableLanguages } from "#/i18n";
+
+// The sidebar's "Search commands" trigger is the command menu's accessible
+// name, so it must be read out in the user's language (#17909). Lock this down
+// at translation.json because the test i18next mock returns keys.
+describe("COMMAND_MENU$OPEN_LABEL label", () => {
+ const translationPath = path.join(
+ __dirname,
+ "../../src/i18n/translation.json",
+ );
+ const translation = JSON.parse(
+ fs.readFileSync(translationPath, "utf-8"),
+ ) as Record<string, Record<string, string>>;
+ const label = translation.COMMAND_MENU$OPEN_LABEL;
+
+ it.each(
+ AvailableLanguages.map(({ value }) => value).filter((lng) => lng !== "en"),
+ )("is translated for %s", (lng) => {
+ expect(label[lng]).toBeTruthy();
+ expect(label[lng]).not.toBe(label.en);
+ });
+});
diff --git a/__tests__/routes/root-layout.test.tsx b/__tests__/routes/root-layout.test.tsx
index 308ee20fff..081c942a60 100644
--- a/__tests__/routes/root-layout.test.tsx
+++ b/__tests__/routes/root-layout.test.tsx
@@ -15,6 +15,7 @@ const migrateEnabledSkillsMock = vi.fn();
const syncTelemetryConsentMock = vi.fn();
const syncAutomationTelemetryConsentMock = vi.fn();
const telemetryIdentityMock = vi.fn();
+const syncDocumentLanguageMock = vi.fn();
vi.mock("#/hooks/query/use-config", () => ({
useConfig: () => useConfigMock(),
@@ -40,6 +41,10 @@ vi.mock("#/hooks/use-telemetry-identity", () => ({
useTelemetryIdentity: () => telemetryIdentityMock(),
}));
+vi.mock("#/hooks/use-sync-document-language", () => ({
+ useSyncDocumentLanguage: () => syncDocumentLanguageMock(),
+}));
+
vi.mock("#/hooks/use-ensure-active-profile", () => ({
useEnsureActiveProfile: () => ensureActiveProfileMock(),
}));
@@ -258,6 +263,7 @@ describe("root layout", () => {
expect(syncAutomationTelemetryConsentMock).toHaveBeenCalledOnce();
expect(telemetryIdentityMock).toHaveBeenCalledOnce();
expect(ensureActiveProfileMock).toHaveBeenCalledOnce();
+ expect(syncDocumentLanguageMock).toHaveBeenCalledOnce();
expect(document.title).toBe("OpenHands");
expect(
await screen.findByTestId("environment-switch-overlay"),
diff --git a/__tests__/routes/settings.test.tsx b/__tests__/routes/settings.test.tsx
index 7ca95e07bc..8886e45773 100644
--- a/__tests__/routes/settings.test.tsx
+++ b/__tests__/routes/settings.test.tsx
@@ -134,6 +134,38 @@ describe("settings route", () => {
expect(screen.getByTestId("app-settings-screen")).toBeInTheDocument();
});
+ it("exposes a single main landmark that holds the settings page", () => {
+ // Arrange
+ const RouterStub = createRoutesStub([
+ {
+ path: "/settings",
+ Component: SettingsScreen,
+ children: [
+ {
+ path: "/settings/app",
+ Component: () => <div data-testid="app-settings-screen" />,
+ },
+ ],
+ },
+ ]);
+
+ // Act
+ render(
+ <QueryClientProvider client={new QueryClient()}>
+ <ActiveBackendProvider>
+ <RouterStub initialEntries={["/settings/app"]} />
+ </ActiveBackendProvider>
+ </QueryClientProvider>,
+ );
+
+ // Assert — nested <main> elements give screen readers two landmarks.
+ const landmarks = screen.getAllByRole("main");
+ expect(landmarks).toHaveLength(1);
+ expect(landmarks[0]).toContainElement(
+ screen.getByTestId("app-settings-screen"),
+ );
+ });
+
it("keeps the section title of a page that is not in the listed navigation", () => {
// Arrange — the nav mock above lists only LLM + Application, mirroring a
// locked-to-Cloud deployment where deep-linked pages stay routable but are
diff --git a/src/components/features/sidebar/sidebar-nav-link.tsx b/src/components/features/sidebar/sidebar-nav-link.tsx
index 2749ed8c55..5c8f24d281 100644
--- a/src/components/features/sidebar/sidebar-nav-link.tsx
+++ b/src/components/features/sidebar/sidebar-nav-link.tsx
@@ -44,7 +44,8 @@ interface SidebarNavLinkProps {
collapsed?: boolean;
hoverContent?: React.ReactNode;
/**
- * When true, forces the active style regardless of the current path.
+ * When true, forces the active style (and `aria-current`) regardless of the
+ * current path.
* Useful for links that should appear active for multiple related routes
* (e.g. the Extensions link being active on /mcp and /plugins too).
*/
@@ -77,6 +78,7 @@ export function SidebarNavLink({
data-testid={testId}
tabIndex={disabled ? -1 : 0}
aria-label={collapsed ? label : undefined}
+ aria-current={active ? "page" : undefined}
// Announce the disabled state to assistive tech. The visual disabled
// styling plus tabIndex=-1 + preventDefault gives sighted/keyboard users
// the right behaviour already; this closes the screen-reader gap so the
diff --git a/src/components/shared/navigation-link.tsx b/src/components/shared/navigation-link.tsx
index 06e3a2fe25..2f145d9f93 100644
--- a/src/components/shared/navigation-link.tsx
+++ b/src/components/shared/navigation-link.tsx
@@ -62,6 +62,7 @@ export const NavigationLink = React.forwardRef<
children,
target,
rel,
+ "aria-current": ariaCurrent,
...props
},
ref,
@@ -97,7 +98,9 @@ export const NavigationLink = React.forwardRef<
rel={rel}
onClick={handleClick}
className={resolvedClassName}
- aria-current={isActive ? "page" : undefined}
+ // A caller that knows the link stands for a whole section (e.g. the
+ // sidebar Customize row on /mcp) can mark it current explicitly.
+ aria-current={ariaCurrent ?? (isActive ? "page" : undefined)}
>
{children}
</a>
diff --git a/src/hooks/use-sync-document-language.ts b/src/hooks/use-sync-document-language.ts
new file mode 100644
index 0000000000..02f6b5bce0
--- /dev/null
+++ b/src/hooks/use-sync-document-language.ts
@@ -0,0 +1,25 @@
+import React from "react";
+import i18n from "#/i18n";
+
+/**
+ * Mirrors the active UI language onto `<html lang>` and `<html dir>` so
+ * screen readers switch voice and right-to-left scripts get `dir="rtl"`.
+ * Standalone app only: an embedding host owns its own document element.
+ */
+export function useSyncDocumentLanguage() {
+ React.useEffect(() => {
+ const applyLanguage = (language: string) => {
+ const root = document.documentElement;
+ root.lang = language;
+ root.dir = i18n.dir(language);
+ };
+
+ if (i18n.language) {
+ applyLanguage(i18n.language);
+ }
+ i18n.on("languageChanged", applyLanguage);
+ return () => {
+ i18n.off("languageChanged", applyLanguage);
+ };
+ }, []);
+}
diff --git a/src/i18n/translation.json b/src/i18n/translation.json
index 6aac13a951..36e523e1c3 100644
--- a/src/i18n/translation.json
+++ b/src/i18n/translation.json
@@ -36771,21 +36771,21 @@
"zh-TW": "Command menu"
},
"COMMAND_MENU$OPEN_LABEL": {
- "ar": "Search commands",
- "ca": "Search commands",
- "de": "Search commands",
+ "ar": "البحث في الأوامر",
+ "ca": "Cerca ordres",
+ "de": "Befehle durchsuchen",
"en": "Search commands",
- "es": "Search commands",
- "fr": "Search commands",
- "it": "Search commands",
+ "es": "Buscar comandos",
+ "fr": "Rechercher des commandes",
+ "it": "Cerca comandi",
"ja": "コマンドを検索",
- "ko-KR": "Search commands",
- "no": "Search commands",
- "pt": "Search commands",
+ "ko-KR": "명령 검색",
+ "no": "Søk etter kommandoer",
+ "pt": "Pesquisar comandos",
"tr": "Komutlarda ara",
- "uk": "Search commands",
- "zh-CN": "Search commands",
- "zh-TW": "Search commands"
+ "uk": "Пошук команд",
+ "zh-CN": "搜索命令",
+ "zh-TW": "搜尋指令"
},
"COMMAND_MENU$CLOSE_LABEL": {
"ar": "Close command menu",
diff --git a/src/routes/root-layout.tsx b/src/routes/root-layout.tsx
index eb430ae614..da7a70c9ce 100644
--- a/src/routes/root-layout.tsx
+++ b/src/routes/root-layout.tsx
@@ -19,6 +19,7 @@ import { useSyncTelemetryConsent } from "#/hooks/use-sync-telemetry-consent";
import { useSyncAutomationTelemetryConsent } from "#/hooks/use-sync-automation-telemetry-consent";
import { useTelemetryIdentity } from "#/hooks/use-telemetry-identity";
+import { useSyncDocumentLanguage } from "#/hooks/use-sync-document-language";
import { LoadingSpinner } from "#/components/shared/loading-spinner";
import { CloudOrganizationBoundary } from "#/components/features/backends/cloud-organization-boundary";
import { useAppTitle } from "#/hooks/use-app-title";
@@ -102,6 +103,7 @@ function MainAppContent() {
i18n.changeLanguage(settings.language);
}
}, [settings?.language]);
+ useSyncDocumentLanguage();
if (config.isLoading) {
return (
diff --git a/src/routes/settings.tsx b/src/routes/settings.tsx
index cb5f69f21a..a055aba346 100644
--- a/src/routes/settings.tsx
+++ b/src/routes/settings.tsx
@@ -99,8 +99,9 @@ function SettingsScreen() {
return <Navigate to={LOCKED_CLOUD_SETTINGS_NAV_PATH} replace />;
}
+ // SettingsLayout renders the page's only <main> landmark (#17909).
return (
- <main data-testid="settings-screen" className="min-h-0">
+ <div data-testid="settings-screen" className="min-h-0">
<SettingsSectionHeaderProvider
setHideSectionHeader={setHideSectionHeader}
>
@@ -123,7 +124,7 @@ function SettingsScreen() {
</div>
</SettingsLayout>
</SettingsSectionHeaderProvider>
- </main>
+ </div>
);
}