Languages, themes, and accessibility

This reference describes how the desktop client chooses its language, colours, fonts, and accessibility adjustments, and where it keeps these choices. It covers i18n/translator.py, i18n/en.json, i18n/tr.json, themes/theme_engine.py, themes/style.qss, core/accessibility_manager.py, core/settings_store.py, widgets/preferences_dialog.py, and widgets/accessibility_dialog.py under src/cluster_erp/desktop/. The web client's equivalents are on internationalisation and languages and themes, tokens, and accessibility.

Scope and source¶

• Defined in: Translator (src/cluster_erp/desktop/i18n/translator.py:32), ThemeEngine and THEMES (src/cluster_erp/desktop/themes/theme_engine.py:661-881), AccessibilityManager (src/cluster_erp/desktop/core/accessibility_manager.py:207), SettingsStore (src/cluster_erp/desktop/core/settings_store.py:8).
• Counts: language keys were counted as the top-level keys of each JSON file; theme tokens as the keys of each THEMES palette; stylesheet tokens as the distinct @name placeholders in style.qss, excluding the word in its header comment; icons as the keys of _ICON_PATHS; settings keys by searching for calls of get, set, and remove on the settings store and QSettings.

Language files¶

Both files have the same key set. The keys are flat strings with a dotted prefix. The largest prefixes are procurement (269 keys), error (177), bom_explorer (174), chat (123), nesting_job (74), resource (58), product (56), purq (54), logs (54), and common (48). The folder also holds an empty file en_keys.txt.

Translator¶

A new desktop language is a new JSON file in src/cluster_erp/desktop/i18n/. The language selectors of the sign-in dialog and the preferences dialog list every file that available_languages finds (src/cluster_erp/desktop/widgets/login_dialog.py:214-226, src/cluster_erp/desktop/widgets/preferences_dialog.py:62-69). The desktop folder has no languages.json. The API client sends the current language as Accept-Language and follows every change (src/cluster_erp/desktop/main.py:169-172).

Widgets that show translated text connect to Translator.language_changed and set their texts again. For example MainWindow._retranslate_ui renames section tabs (src/cluster_erp/desktop/widgets/main_window.py:64, src/cluster_erp/desktop/widgets/main_window.py:628-648).

Theme engine¶

ThemeEngine reads the setting theme, default dark, and applies it at once (src/cluster_erp/desktop/themes/theme_engine.py:717-726). Applying a theme does four things (src/cluster_erp/desktop/themes/theme_engine.py:798-848):

1. It merges the palette with the current overrides from accessibility.
2. It sets a QPalette for the application from the merged values.
3. It writes the icon SVG files in the icon colour and the check-box SVG files, only when their colours changed.
4. It reads style.qss, replaces each @token with its value, longest token name first, sets the stylesheet, and repolishes every widget.

set_overrides waits 150 ms before it applies, so several changes in a row cause one repaint (src/cluster_erp/desktop/themes/theme_engine.py:777-790). toggle switches between light and dark (src/cluster_erp/desktop/themes/theme_engine.py:880-881). current_colors returns the merged palette for widgets that paint themselves (src/cluster_erp/desktop/themes/theme_engine.py:875-878).

Theme tokens¶

Each palette has 24 keys (src/cluster_erp/desktop/themes/theme_engine.py:661-714). style.qss uses 20 of them plus cb-dir, the folder of the generated check-box images (src/cluster_erp/desktop/themes/theme_engine.py:844).

The four keys marked no are read by widgets through current_colors, for example the sidebar (src/cluster_erp/desktop/widgets/sidebar.py:321-334) and the status bar (src/cluster_erp/desktop/widgets/status_bar.py:76-88).

Icons¶

_ICON_PATHS holds 123 icon glyphs as SVG path fragments (src/cluster_erp/desktop/themes/theme_engine.py:23-649). The engine writes them as files in a temporary folder in the dimmed colour, and icon(name) loads a file, or returns an empty icon for an unknown name (src/cluster_erp/desktop/themes/theme_engine.py:14, src/cluster_erp/desktop/themes/theme_engine.py:652-654, src/cluster_erp/desktop/themes/theme_engine.py:728-734). Metadata sections and actions name icons by these keys (src/cluster_erp/desktop/widgets/sidebar.py:202-205).

Accessibility settings¶

AccessibilityManager reads its settings under the prefix accessibility/, computes theme overrides, and emits settings_changed after every change (src/cluster_erp/desktop/core/accessibility_manager.py:195, src/cluster_erp/desktop/core/accessibility_manager.py:207-237). main() applies them before the sign-in dialog (src/cluster_erp/desktop/main.py:164-165).

A stored high-contrast value dark is migrated to light; any other unknown value becomes off (src/cluster_erp/desktop/core/accessibility_manager.py:221-229). reset_all removes the seven adjustable settings and applies the defaults (src/cluster_erp/desktop/core/accessibility_manager.py:330-352). When the theme changes, the overrides are computed again if any adjustment is active (src/cluster_erp/desktop/core/accessibility_manager.py:431-446).

The Accessibility dialog (key accessibility.title) offers segmented controls for font size, high contrast, colour-blind mode, and reading background, a brightness slider from 50 to 150, check boxes for reduced motion and the dyslexia font, and Reset All Settings (key accessibility.reset_all) with a confirmation (src/cluster_erp/desktop/widgets/accessibility_dialog.py:216-400, src/cluster_erp/desktop/widgets/accessibility_dialog.py:477-489). It opens from the sidebar, from the sign-in dialog, and through MainWindow._show_accessibility (src/cluster_erp/desktop/widgets/sidebar.py:129, src/cluster_erp/desktop/widgets/login_dialog.py:230-240, src/cluster_erp/desktop/widgets/main_window.py:614-624).

Preferences dialog¶

The Preferences dialog (key settings.title) applies each change at once and saves it (src/cluster_erp/desktop/widgets/preferences_dialog.py:37-133):

Local settings¶

SettingsStore wraps QSettings with the organisation ClusterERP and the application DesktopClient, and writes through at once (src/cluster_erp/desktop/core/settings_store.py:8-21). The client uses 16 keys:

get_user_timezone and BomExplorer read the same store through their own QSettings objects (src/cluster_erp/desktop/core/timezone_utils.py:37-43, src/cluster_erp/desktop/modules/bom/bom_explorer.py:1412-1419).

Constraints and validation¶

• Setters ignore values outside their lists, and brightness is clamped to 50 to 150 (src/cluster_erp/desktop/core/accessibility_manager.py:278-328).
• An unknown time zone name falls back to UTC (src/cluster_erp/desktop/core/timezone_utils.py:37-43).
• No code outside AccessibilityManager and the accessibility dialog reads reduced_motion, found by searching src/cluster_erp/desktop/ for the name.
• Desktop language files are also checked by tests outside the desktop folder, for example for the presence of error keys (tests/test_bom_bugfix_batch_2026_10_08.py:123-130).

Discrepancies¶

Terms introduced¶

Related pages¶

• Desktop client
• Run the desktop client
• Internationalisation and languages
• Themes, tokens, and accessibility
• Data-driven languages

Verified against commit 92f8051 on 2026-11-13.