Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(ok): give the Excalidraw board the reader's language (PRD-8471) (#4177)

Andrew Mikofalvy8e630b35cf36
diff --git a/.changeset/excalidraw-board-language.md b/.changeset/excalidraw-board-language.md
new file mode 100644
index 000000000..3c93ceeb0
--- /dev/null
+++ b/.changeset/excalidraw-board-language.md
@@ -0,0 +1,7 @@
+---
+'@inkeep/open-knowledge': patch
+---
+
+Excalidraw boards now follow the language you have set for the rest of the app. The board's toolbar, menus, and settings, including the stroke Pressure control, were English no matter which language you chose.
+
+Simplified Chinese, Traditional Chinese, Spanish, French, Portuguese (Brazil), Indonesian and Korean all get a translated board, as does Arabic, which the language picker does not list yet. Hindi, Bengali, and Urdu keep an English board, because Excalidraw does not offer a translation for them that it considers complete enough to ship, and a board that is half translated is harder to read than one that is not translated at all. No drawing is affected. One knock-on effect is worth naming: Excalidraw sets the page's language and text direction from whatever board language is active, so on the eight translated languages the page now reports the language you are actually reading, which is what screen readers announce. On the three that stay English it reports English, exactly as it did before.
diff --git a/docs/content/contribute/translations.mdx b/docs/content/contribute/translations.mdx
index 20e3c47fe..51c9f66ca 100644
--- a/docs/content/contribute/translations.mdx
+++ b/docs/content/contribute/translations.mdx
@@ -60,6 +60,7 @@ packages/app/src/locales/<locale>/messages.po
- **User Generated content is NEVER translated:&#x20;**Document bodies, titles, file and folder names, frontmatter values and tags stay exactly as you wrote them, in every language.
- **The CLI's commands, flags and machine-readable output REMAIN English ONLY** on purpose, so scripts keep working whatever the machine's locale is.
- **This documentation site is English only** for now.
+- **The embedded Excalidraw board follows the interface language wherever Excalidraw offers a translation for it.** The board's toolbar, menus and settings come from Excalidraw itself rather than from these catalogs, so translating them here is not possible. Hindi, Bengali and Urdu get an English board, because Excalidraw does not offer a translation for them that it considers complete enough to ship; every other supported language gets a translated one.
## A language that isn't on the list
diff --git a/packages/app/src/components/ExcalidrawDocEditor.langcode.dom.test.tsx b/packages/app/src/components/ExcalidrawDocEditor.langcode.dom.test.tsx
new file mode 100644
index 000000000..9f3b56ee8
--- /dev/null
+++ b/packages/app/src/components/ExcalidrawDocEditor.langcode.dom.test.tsx
@@ -0,0 +1,75 @@
+import { useLingui as useLinguiRuntime } from '@lingui/react';
+import { act, cleanup, render } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import * as Y from 'yjs';
+import * as linguiShim from '../../tests/lingui-macro-shim';
+
+const boardProps: Record<string, unknown>[] = [];
+
+vi.doMock('@excalidraw/excalidraw', () => ({
+ CaptureUpdateAction: { NEVER: 'never' },
+ Excalidraw: (props: Record<string, unknown>) => {
+ boardProps.push(props);
+ return <div data-testid="excalidraw-stub" />;
+ },
+ restoreElements: (elements: unknown) => (elements as unknown[] | undefined) ?? [],
+ restoreAppState: () => ({}),
+ serializeAsJSON: () => '{}',
+ getNonDeletedElements: (elements: unknown) => elements,
+}));
+
+vi.doMock('./MermaidDocEditor', () => ({ replaceYText: vi.fn() }));
+
+vi.doMock('@lingui/react/macro', () => ({
+ ...linguiShim,
+ useLingui: () => ({ ...useLinguiRuntime(), t: linguiShim.t }),
+}));
+
+async function renderBoard(locale: string) {
+ const { ExcalidrawDocEditor } = await import('./ExcalidrawDocEditor.tsx');
+ const { I18nProvider } = await import('@lingui/react');
+ const { i18n } = await import('@lingui/core');
+ i18n.activate(locale);
+ const doc = new Y.Doc();
+ render(
+ <I18nProvider i18n={i18n}>
+ <ExcalidrawDocEditor provider={{ document: doc } as never} />
+ </I18nProvider>,
+ );
+ return i18n;
+}
+
+function latestLangCode() {
+ return boardProps.at(-1)?.langCode;
+}
+
+describe('the Excalidraw board editor', () => {
+ beforeEach(() => {
+ boardProps.length = 0;
+ });
+
+ afterEach(cleanup);
+
+ test('hands the board the language the reader is already using', async () => {
+ await renderBoard('zh-Hans');
+
+ expect(latestLangCode()).toBe('zh-CN');
+ });
+
+ test('hands the board English when the reader has no board translation', async () => {
+ await renderBoard('ur');
+
+ expect(latestLangCode()).toBe('en');
+ });
+
+ test('follows a language switch made while the board is already open', async () => {
+ const i18n = await renderBoard('en');
+ expect(latestLangCode()).toBe('en');
+
+ act(() => {
+ i18n.activate('zh-Hans');
+ });
+
+ expect(latestLangCode()).toBe('zh-CN');
+ });
+});
diff --git a/packages/app/src/components/ExcalidrawDocEditor.tsx b/packages/app/src/components/ExcalidrawDocEditor.tsx
index 2e64fc5d6..ea263c1e0 100644
--- a/packages/app/src/components/ExcalidrawDocEditor.tsx
+++ b/packages/app/src/components/ExcalidrawDocEditor.tsx
@@ -7,6 +7,7 @@ import { type ComponentProps, useEffect, useRef, useState } from 'react';
import { replaceYText } from './MermaidDocEditor';
import '@/lib/excalidraw-env';
+import { excalidrawLangCode } from '@/lib/excalidraw-lang.ts';
import { type ExcalidrawScene, restoreScene, serializeScene } from '@/lib/excalidraw-scene.ts';
type ExcalidrawProps = ComponentProps<typeof Excalidraw>;
@@ -27,7 +28,7 @@ function parseSnapshot(str: string): ParseOutcome {
}
export function ExcalidrawDocEditor({ provider }: { provider: HocuspocusProvider }) {
- const { t } = useLingui();
+ const { t, i18n } = useLingui();
const ytext = provider.document.getText('source');
const [excalidrawAPI, setExcalidrawAPI] = useState<ExcalidrawImperativeAPI | null>(null);
@@ -90,6 +91,7 @@ export function ExcalidrawDocEditor({ provider }: { provider: HocuspocusProvider
onExcalidrawAPI={setExcalidrawAPI}
initialData={initialOutcome.scene}
onChange={handleChange}
+ langCode={excalidrawLangCode(i18n.locale)}
/>
</div>
</main>
diff --git a/packages/app/src/lib/excalidraw-lang.dom.test.ts b/packages/app/src/lib/excalidraw-lang.dom.test.ts
new file mode 100644
index 000000000..36149bfd9
--- /dev/null
+++ b/packages/app/src/lib/excalidraw-lang.dom.test.ts
@@ -0,0 +1,51 @@
+import { languages } from '@excalidraw/excalidraw';
+import { SUPPORTED_LOCALES } from '@inkeep/open-knowledge-core';
+import { describe, expect, test } from 'vitest';
+import {
+ BOARD_FALLBACK_LOCALES,
+ EXCALIDRAW_FALLBACK_LANG_CODE,
+ excalidrawLangCode,
+} from './excalidraw-lang.ts';
+
+const offered = new Set(languages.map((language) => language.code));
+
+describe('the Excalidraw language mapping', () => {
+ test('this build really does offer the codes the rest of these tests check against', () => {
+ expect(offered.size).toBeGreaterThan(15);
+ expect(offered.has(EXCALIDRAW_FALLBACK_LANG_CODE)).toBe(true);
+ });
+
+ test.each(SUPPORTED_LOCALES)('maps %s to a language this build offers', (locale) => {
+ expect(offered.has(excalidrawLangCode(locale))).toBe(true);
+ });
+
+ test('falls back only where upstream withholds the language from its own list', () => {
+ expect([...BOARD_FALLBACK_LOCALES].sort()).toEqual(['bn', 'hi', 'ur']);
+
+ const languageSubtags = new Set([...offered].map((code) => code.split('-')[0]));
+ expect(languageSubtags.has('ko')).toBe(true);
+
+ for (const locale of BOARD_FALLBACK_LOCALES) {
+ expect(languageSubtags.has(locale)).toBe(false);
+ }
+ });
+
+ test('falls back rather than handing the board a code it does not know', () => {
+ expect(excalidrawLangCode('kl-GL')).toBe(EXCALIDRAW_FALLBACK_LANG_CODE);
+ expect(excalidrawLangCode('')).toBe(EXCALIDRAW_FALLBACK_LANG_CODE);
+ });
+
+ test.each([
+ 'toString',
+ 'constructor',
+ '__proto__',
+ 'valueOf',
+ ])('returns a language code for the inherited key %s rather than something off the prototype', (key) => {
+ expect(excalidrawLangCode(key)).toBe(EXCALIDRAW_FALLBACK_LANG_CODE);
+ });
+
+ test('keeps the two Chinese scripts on separate catalogs', () => {
+ expect(excalidrawLangCode('zh-Hans')).toBe('zh-CN');
+ expect(excalidrawLangCode('zh-Hant')).toBe('zh-TW');
+ });
+});
diff --git a/packages/app/src/lib/excalidraw-lang.ts b/packages/app/src/lib/excalidraw-lang.ts
new file mode 100644
index 000000000..e7b9cc2ba
--- /dev/null
+++ b/packages/app/src/lib/excalidraw-lang.ts
@@ -0,0 +1,31 @@
+import { SUPPORTED_LOCALES, type SupportedLocale } from '@inkeep/open-knowledge-core';
+
+export const EXCALIDRAW_FALLBACK_LANG_CODE = 'en';
+
+const EXCALIDRAW_LANG_CODE_BY_LOCALE = {
+ en: 'en',
+ 'zh-Hans': 'zh-CN',
+ 'zh-Hant': 'zh-TW',
+ hi: null,
+ es: 'es-ES',
+ ar: 'ar-SA',
+ fr: 'fr-FR',
+ bn: null,
+ 'pt-BR': 'pt-BR',
+ id: 'id-ID',
+ ur: null,
+ ko: 'ko-KR',
+} as const satisfies Record<SupportedLocale, string | null>;
+
+export const BOARD_FALLBACK_LOCALES = SUPPORTED_LOCALES.filter(
+ (locale) => EXCALIDRAW_LANG_CODE_BY_LOCALE[locale] === null,
+);
+
+function isMappedLocale(locale: string): locale is SupportedLocale {
+ return Object.hasOwn(EXCALIDRAW_LANG_CODE_BY_LOCALE, locale);
+}
+
+export function excalidrawLangCode(locale: string): string {
+ if (!isMappedLocale(locale)) return EXCALIDRAW_FALLBACK_LANG_CODE;
+ return EXCALIDRAW_LANG_CODE_BY_LOCALE[locale] ?? EXCALIDRAW_FALLBACK_LANG_CODE;
+}
diff --git a/packages/app/vitest.dom.config.ts b/packages/app/vitest.dom.config.ts
index b6960a73f..010b253c5 100644
--- a/packages/app/vitest.dom.config.ts
+++ b/packages/app/vitest.dom.config.ts
@@ -29,9 +29,8 @@ export const appDomVitestConfig = {
...appVitestConfig.resolve.alias,
// Excalidraw's dev bundle imports `roughjs/bin/rough` without the
// extension, which Vite's Node resolver rejects. The browser build
- // resolves it through bundling, so this only bites the one tier that
- // imports the real package rather than stubbing it
- // (`excalidraw-scene.roundtrip.dom.test.ts`). Drop this alias if a
+ // resolves it through bundling, so this only bites the suites that
+ // import the real package rather than stubbing it. Drop this alias if a
// future Excalidraw ships the extension.
{ find: /^roughjs\/bin\/rough$/, replacement: 'roughjs/bin/rough.js' },
],
@@ -57,9 +56,7 @@ export const appDomVitestConfig = {
hookTimeout: 30_000,
isolate: true,
// Route the real Excalidraw through Vite's transform rather than Node's
- // resolver, so the `roughjs/bin/rough` alias above is honoured. Only the
- // round-trip suite imports the package for real; every other Excalidraw
- // test stubs it via `vi.doMock`, which intercepts ahead of resolution.
+ // resolver, so the `roughjs/bin/rough` alias above is honoured.
server: { deps: { inline: [/@excalidraw[/\\]excalidraw/] } },
},
} satisfies ViteUserConfig;