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.

Parameters:

• sources – English UI strings; each is converted with str and duplicates are counted once.

• language – language code to check; None uses the current language.

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.

Parameters:

• text – the English UI string, converted with str. For English itself the answer is whether the string is a catalog row.

• language – language code to check; None uses the current language.

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.

Parameters:

app – the QApplication to install the event filter on. None does nothing, and an application that already has the filter is left as it is.

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.

Parameters:

• app – the QApplication the qtbase translator is installed on; None returns False.

• language – language code to load; None uses the current language. English and languages without a Qt catalog install nothing.

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.

Parameters:

code – any value; converted with str (None and other falsy values count as empty), hyphens read as underscores and matched case-insensitively. Anything unrecognised returns DEFAULT_LANGUAGE.

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.

Parameters:

• root – the widget (or other QObject) whose child widgets and actions are walked; it is included itself when it is a QWidget. None does nothing.

• language – language code to translate into; None uses the current language.

• only_new – skip widgets already stamped for this language and catalog generation, as described above.

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.

Parameters:

• widget – a widget with setText; the template and values are stored on it so a later language pass can re-render the text.

• source – the English template, translated with tr().

• language – language code; None uses the current language.

• values – placeholder values applied with str.format after translation.

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.

Parameters:

• text – the English UI string, converted with str.

• language – language code; None uses the current language.

• values – placeholder values for str.format; a template the values do not fit is returned unformatted.