craft-libs/docs/language-testing.md

Language testing per release

A manual checklist for each app release: input methods, keyboard layouts and screen readers on real systems. Copy it into the release issue and tick each item; for a failure, note the system, its version and what happened instead, and open an issue.

Run every input item in two places: a single-line text field (a rename or search field) and the app's canvas text tool, if it has one. "Commits" means the text appears in the field as ordinary text, once, at the caret, with the composition underline gone.

What is automated

Leave these to the automated tests; repeat them by hand only to investigate a failure.

Automated	Where
Linux input methods on this box: fcitx5 on Xvfb (XIM), fcitx5 on headless sway (text-input-v3) and IBus on Xvfb; Pinyin, Hangul, Telex and Anthy compositions, a click into a composing field, a pointer unplugged while composing	IME harness, tools/ime-harness/
Each app's key screens in Arabic, Japanese, Traditional Chinese, Korean, Thai and Vietnamese with no system fonts; one scripted IME composition and one non-Latin shortcut per app	craft_ui::testing (craft-ui README)
The shortcut rule for Russian, Arabic 101, Hebrew, Greek, Thai, AZERTY, Dvorak and QWERTZ presses as egui reports them	craft-keymap's tests

The manual list covers what those can't reach: the input methods and layouts of Windows and macOS, desktop Linux sessions, the browser on phones, and screen readers.

Release

• App and version:
• Tester and date:
• Builds tested (Windows, macOS, Linux, Flatpak, FreeBSD, web):

Windows

• Microsoft Pinyin. Type nihao, then Space. The candidate window opens at the caret; 你好 commits. Type nihao and press Enter: nihao commits as Latin text.
• Microsoft Japanese IME. Type nihongo, then Space. にほんご converts to 日本語 with the converted segment underlined; Enter commits 日本語. Type nihongo again and press Escape twice: the composition is removed, nothing is inserted, and the dialog or panel stays open.
• Microsoft Korean IME (2-Set). Switch with the Han/Eng key or Right Alt. Type gksrmf: the syllables build in place and 한글 commits. While composing 한, Backspace leaves 하. Press Enter after a syllable: the syllable commits and the field does not also submit; a second Enter does.
• Sogou Pinyin. Type zhongguo, then Space: 中国 commits, with Sogou's candidate bar at the caret. In Chinese mode, , types the full-width ，.
• UniKey (Telex). Type Vieejt Nam: Việt Nam commits with no doubled or missing letters. Type tieesng in the canvas text tool: tiếng.
• Emoji panel. Press Win+. and pick 😀: it is inserted once, at the caret. Pick a second emoji with the panel still open: it follows the first.
• AltGr layouts. On German, AltGr+Q types @ and AltGr+E types €; on Polish (programmer's), AltGr+A types ą. None of these runs a Ctrl+Alt shortcut.
• US-International dead keys. Type ' then e: é. Type ' then Space: '.

macOS

• Pinyin – Simplified. Type nihao, then Space: the candidate window opens at the caret and 你好 commits.
• Japanese – Romaji (Kotoeri). Type nihongo, then Space: 日本語 is shown with the active segment underlined more thickly; Return commits. Escape during a composition cancels it without closing the dialog.
• 2-Set Korean. Type gksrmf: 한글 builds in place and commits. Return after a syllable commits it without submitting the field; a second Return submits.
• Press and hold. Hold e: the accent menu opens at the caret; press 2: é replaces the e. The plain e is not left behind.
• Dead keys (U.S. layout). Option+E then e: é. Option+U then u: ü. Option+N then n: ñ. The pending accent shows as marked text until the second key.
• Character Viewer. Press Ctrl+Cmd+Space and pick 😀: it is inserted once, at the caret.
• Dictation. Start dictation (press Fn twice, or the microphone key) and say a short sentence: interim text appears at the caret; stopping dictation leaves the sentence once.

Linux

• GNOME with IBus (Wayland session). With ibus-libpinyin, nihao Space: 你好. With ibus-hangul, gksrmf: 한글. With ibus-mozc or ibus-anthy, nihongo Space Enter: 日本語. The candidate popup opens at the caret.
• KDE Plasma with Fcitx5 (Wayland session). The same three compositions through fcitx5-chinese-addons, fcitx5-hangul and fcitx5-mozc. The preedit shows in the field while composing (designcraft#1234).
• Hyprland with Fcitx5. The same three compositions; the candidate popup follows the caret when the caret moves to a second line.
• X11 with Vietnamese Telex. In an X11 session with fcitx5-unikey or ibus-unikey, type tieesng Vieejt: tiếng Việt, with no doubled letters.
• One Flatpak build. Install the app's Flatpak and repeat one composition (Pinyin or Hangul) through the host's input method. Switch the UI to Japanese and to Arabic: every label draws without boxes, with only the runtime's fonts.

FreeBSD (once per release cycle)

• Build and start the app. Under X11 with fcitx5 or IBus, compose nihao → 你好 and gksrmf → 한글. Switch the UI to Arabic: labels join and run right to left.

Web

• Android, Chrome, Gboard. Type hello wrold with suggestions on: the composing word is underlined, and the autocorrected world replaces it without duplicating text. Backspace deletes one character at a time. Switch Gboard to Korean and type 한글: syllables build in place.
• iOS, Safari, Korean keyboard. Type 한글: syllables build in place with no doubled jamo; tapping elsewhere in the text commits the syllable and moves the caret there.

Keyboard shortcuts on other layouts

For each layout, run Copy, Paste, Undo, Select All and Save from the keyboard, and the shortcuts named below. Each should run the same command it runs on US QWERTY, and the menus should show the shortcut as listed. On macOS read Ctrl as Cmd.

• Russian. Ctrl on the C, V, Z, A and S keys (с, м, я, ф, ы) copies, pastes, undoes, selects all and saves. The menu shows Ctrl+[ as Ctrl+Х.
• Arabic 101. Ctrl on the C, V, Z, A and S keys (ؤ, ر, ئ, ش, س) runs the same commands.
• Hebrew. Ctrl on the C, V, Z, A and S keys (ב, ה, ז, ש, ד) runs the same commands. Ctrl on the Q key, which types /, runs the Ctrl+Q command, not Ctrl+/.
• Greek. Ctrl on the C, V, Z, A and S keys (ψ, ω, ζ, α, σ) runs the same commands. In a text field, ; then α types ά.
• Thai (Kedmanee). Ctrl on the C, V, Z, A and S keys (แ, อ, ผ, ฟ, ห) runs the same commands. Ctrl on the 1 key, which types ๅ, runs Ctrl+1.
• AZERTY (French). Ctrl+A and Ctrl+Z are the keys labelled A and Z. Ctrl on the 1 key (&) runs Ctrl+1. Ctrl on the 6 key (-) zooms out.
• Dvorak. Ctrl+C, Ctrl+V and Ctrl+Z are the keys labelled C, V and Z. Ctrl on the QWERTY Q position, which types ', does not run Ctrl+Q.
• QWERTZ (German). Ctrl+Z undoes and Ctrl+Y redoes, on the keys labelled Z and Y. Ctrl+⇧7 runs Ctrl+/. The menu shows Ctrl+[ as Ctrl+Ü.
• Dvorak – QWERTY ⌘ (macOS). Typing gives Dvorak letters. With Cmd held, the keys follow QWERTY: Cmd on the QWERTY C position copies, and the menus show ⌘C.

Screen readers

Run each with the UI in English, then in Arabic. In Arabic, use a voice that reads Arabic.

• NVDA (Windows). Tab through the main window and one dialog: each control is announced with its name and role, in the UI language, in the order it appears (right to left in Arabic). In a text field, typed characters are echoed and arrow keys read the character passed over. An Arabic file name in an English UI is read in Arabic.
• VoiceOver (macOS). Move with VO+Right through the toolbar and a dialog: names and roles in the UI language, in reading order. The rotor lists the form controls. Composing Hangul in a text field is announced once, when it commits.
• Orca (Linux, GNOME). Tab through the main window and one dialog: names and roles are read in the UI language. Focus moves visibly with each announcement.