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.

Attributes

CATALOGS

DEFAULT_LANGUAGE

ENV_LANGUAGE

LANGUAGES

LANGUAGE_BY_CODE

TERM_CATALOGS

VALID_LANGUAGE_CODES

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.

language_choices(→ tuple[tuple[str, str], Ellipsis])

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_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[source]

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.

code: str[source]
property display_name: str[source]

Return an unambiguous native/English selector label.

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

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

spacr.qt.i18n.current_language() → str[source]

Return the active persisted language without creating an import cycle.

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

Return whether text has an exact or conservative term translation.

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

Return (display label, code) choices for Preferences.

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

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) → None[source]

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.

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

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[source]

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.

spacr.qt.i18n.CATALOGS[source]
spacr.qt.i18n.DEFAULT_LANGUAGE = 'en'[source]
spacr.qt.i18n.ENV_LANGUAGE = 'SPACR_LANGUAGE'[source]
spacr.qt.i18n.LANGUAGES[source]
spacr.qt.i18n.LANGUAGE_BY_CODE[source]
spacr.qt.i18n.TERM_CATALOGS[source]
spacr.qt.i18n.VALID_LANGUAGE_CODES[source]