spacr.qt.i18n

Runtime localization for the spaCR Qt application.

The application historically embedded English text directly in its widgets. Replacing every call site at once would make localization brittle, so this module provides two complementary layers:

• tr() translates text at construction time and always falls back to the original English source string.

• retranslate_widget_tree() safely updates already-created static Qt labels, buttons, menus, tabs, combo-box choices and accessibility text. Original English strings are retained as dynamic Qt properties, allowing a window to switch from Swedish to Korean (for example) without translating a translation. Editable values and user-entered paths are never touched.

Ten languages ship without optional dependencies or network access: English, Swedish, German, Spanish, Simplified Chinese (Mandarin), Portuguese, Hindi, Korean, Icelandic and French. Catalog entries cover application navigation, every registered module, Preferences, common actions and common settings terminology. Uncatalogued scientific or third-party terms remain in English rather than being guessed.

Classes

Language

One selectable UI language.

Functions

catalog_coverage(→ tuple[int, int])	Return (translated, total) for an iterable of source strings.
current_language(→ str)	Return the active persisted language without creating an import cycle.
has_translation(→ bool)	Return whether text has an exact or conservative term translation.
install_dialog_translation(→ None)	Translate transient Qt dialogs when they are shown.
install_qt_translations(→ bool)	Load Qt's own translations for language. True if one loaded.
language_choices(→ tuple[tuple[str, str], ...])	Return (display label, code) choices for Preferences.
normalize_language(→ str)	Return a supported language code, falling back to English.
retranslate_widget_tree(→ None)	Retranslate static text in root and all existing descendants.
set_translatable_items(→ None)	Fill a dropdown with translated captions over untranslatable values.
set_translatable_text(→ None)	Set dynamic UI text while retaining its canonical template and values.
tr(→ str)	Translate one English UI string.

Module Contents

class spacr.qt.i18n.Language

One selectable UI language.

Parameters:

• code – stable persisted language code.

• native_name – language name written in that language.

• english_name – language name written in English.

property display_name: str

Return an unambiguous native/English selector label.

spacr.qt.i18n.catalog_coverage(sources: Iterable[str], language: str | None = None) → tuple[int, int]

Return (translated, total) for an iterable of source strings.

spacr.qt.i18n.current_language() → str

Return the active persisted language without creating an import cycle.

spacr.qt.i18n.has_translation(text: object, language: str | None = None) → bool

Return whether text has an exact or conservative term translation.

spacr.qt.i18n.install_dialog_translation(app) → None

Translate transient Qt dialogs when they are shown.

File pickers, message boxes, input prompts and progress dialogs are often constructed and executed in one expression, so they do not exist during the main-window language pass. An application event filter catches only top-level QDialog show events and applies the same conservative exact catalog translation to their title, labels, buttons and accessible text. Dynamic paths, table data and user text remain outside that traversal.

spacr.qt.i18n.install_qt_translations(app, language: str | None = None) → bool

Load Qt’s own translations for language. True if one loaded.

Idempotent: a translator installed by an earlier call is removed first, so switching language twice does not leave the first one underneath answering for strings the second does not carry.

spacr.qt.i18n.language_choices() → tuple[tuple[str, str], ...]

Return (display label, code) choices for Preferences.

spacr.qt.i18n.normalize_language(code: object) → str

Return a supported language code, falling back to English.

Locale-shaped values such as pt_BR and zh-CN resolve to their bundled base/catalog variants. This also makes a manually edited QSettings file harmless.

spacr.qt.i18n.retranslate_widget_tree(root, language: str | None = None, *, only_new: bool = False) → None

Retranslate static text in root and all existing descendants.

The function is intentionally best-effort and idempotent. It never edits line-edit contents, text editors, table cells, model data, filenames or console output.

Qt’s OWN text follows too – see _follow_qt_own_catalogs() – so a language chosen after launch reaches the right-click menu of every text field, not only the captions spaCR wrote.

only_new skips widgets this pass would translate to exactly what they already say. Every visited widget is stamped with the language it was translated into and the catalog generation that was current; a later pass asked for only_new skips the ones whose stamp still matches. A language change changes the stamp, and so does a catalog gaining a row, so neither can be missed.

IT IS OFF BY DEFAULT AND THAT IS DELIBERATE. A caller that has just replaced a caption itself wants the full pass – _translate_qt_text detects an outside setter by comparing the rendered value, and a skipped widget is not compared. The one caller that asks for it is _LateCaptionTranslator, where three near-root passes an event turn apart re-walk the same tree while a module screen is being assembled.

spacr.qt.i18n.set_translatable_items(combo, sources: Iterable[str], values: Iterable[object] | None = None, language: str | None = None) → None

Fill a dropdown with translated captions over untranslatable values.

A combo box whose entries a handler reads back with currentText() cannot be translated: the caption moves and every comparison misses. That is why the live preview’s dropdowns were marked untranslatable outright, and why the ones that were not marked went wrong quietly – the segmentation object box handed cellen to a worker that only knows cell, and the threshold method wrote medelvärde into a settings key that only accepts mean.

Each entry here carries what the code matches on in its item DATA, so currentData() answers the same English value whatever the caption reads. The English sources are recorded on the widget, so the ordinary language pass re-renders the captions on every later change instead of freezing the language the dropdown happened to be built in.

The selected entry is kept by its value, never by its caption, and signals stay blocked while the entries are replaced.

Parameters:

• combo – the dropdown to fill; its existing entries are replaced.

• sources – the English captions, in order.

• values – what each entry means to the code, in the same order; defaults to sources itself.

• language – language to render in; the current one by default.

Raises:

ValueError – if values is not one value per caption.

spacr.qt.i18n.set_translatable_text(widget, source: str, language: str | None = None, **values: object) → None

Set dynamic UI text while retaining its canonical template and values.

This is for application chrome such as Connecting to {provider}…. User text, AI replies, worker output and scientific results must not use this helper because they intentionally remain untouched by localization.

spacr.qt.i18n.tr(text: object, language: str | None = None, **values: object) → str

Translate one English UI string.

Missing entries intentionally remain English. Keyword values are applied with str.format after translation, allowing catalogs to reorder placeholders safely.