Textual Python TUI localization and gettext guide

Textual Python localization means building a terminal interface whose buttons, messages, input hints and keyboard help can change language without rewriting the records behind them. If you are searching for Textual gettext PO/MO translation, reactive widget labels, multilingual TUI layouts, Rich markup and terminal Unicode testing, this guide shows how those parts fit together in a real application.

Textual is a Python application framework for interactive terminal and browser-style interfaces; Python’s standard-library gettext supports GNU translation catalogs. They are complementary tools, not a single built-in automatic translator. In a maintainable design, the application selects a language, loads an appropriate catalog, translates interface messages and refreshes the relevant widgets while preserving stable IDs and user state.

Consider Harbor Library Desk, a fictional borrowing and room-booking terminal app used by staff in several countries. Its visitor guidance needs natural target-language wording, but book barcodes, account identifiers, dates and room availability must remain accurate. The following practical guide separates these responsibilities and explains initialization, reactive updates, testing, packaging and accessibility.

Quick answer: how to localize Textual Python terminal application responsibly

Select a supported framework and integration version, rather than mixing incompatible examples.
Separate interface messages from immutable IDs, user-provided text, audit events and typed records.
Create reviewable message resources with explicit language choice, grammar and fallback.
Make the chosen language a state change that refreshes all visible controls.
Keep keyboard bindings and application actions independent of translated labels.
Test script shaping, Unicode cell width, long text and small terminal sizes.
Check both success and failure outcomes for truthful user-facing messages.
Package all required catalog assets and verify from a clean installation.
Use fluent human review as well as event tests and snapshots.
Release only the languages and terminal combinations that were actually checked.

Who this guide is for

This guide is for software engineers, technical writers, localization managers, open-source maintainers and product teams who need a dependable multilingual terminal application. It assumes that the reader can follow ordinary Textual Python terminal application concepts but may be new to the difference between rendering a string and designing a translatable user experience. The examples are educational; exact package signatures should always be checked against the pinned release.

The core translation boundary
A working user journey
Twenty-two implementation decisions
Twenty-four troubleshooting situations
Four-week implementation plan
Frequently asked questions
Official documentation and related guides

The core translation boundary

Textual supplies the screen and widget system; Python gettext supplies message lookup. Neither automatically translates user-entered library records, patron names, book identifiers, or reservation states.

A translated interface is a different view of the same task. The safest architecture separates four layers: original records; application decisions and events; message identifiers and values; and terminal rendering. Only the last two layers ordinarily change when the user chooses another language. A value can be formatted differently for readers, but canonical numeric data, identifiers and completed-action records should not be silently overwritten.

For a source string, ask three questions before extraction. Is it something the program itself tells a person? Does its meaning depend on the exact workflow state? Could another person have authored it or used it as an identifier? The first kind belongs in a catalog, the second needs careful message context, and the third usually belongs outside translation. A quotation, file path or record key may be shown next to a localized instruction without becoming a translatable instruction.

This distinction matters across countries because translation changes grammar, date presentation, word order and conventions, not just visible spelling. Never make a promise about work completed unless the event actually succeeded. When an operation is pending, report it as pending; when it fails, identify the recoverable condition without exposing sensitive internal detail. A trustworthy language layer describes the same facts in a voice that readers can understand.

A complete user journey: Harbor Library Desk, a fictional terminal application that helps librarians check borrowed books, reserve community rooms, and prepare multilingual visitor notices

Begin with a real task, not a list of isolated buttons. Open the app using a fresh account or test profile; select a non-default language; navigate to one record; make a harmless change; read a confirmation; and export the resulting record. Repeat the journey with a failure introduced at the moment of writing. Your notes should contain what the user saw, what the application attempted, what the system verified and what was persisted.

The practical advantage of this small journey is that it exposes coupled failures. A new locale may be applied to the initial screen but not a modal. A formatted count may be correct until it reaches zero. A confirmation may use a friendly translated verb even though the export failed. A report may retranslate a source quotation or accidentally change a machine-readable property. These problems appear together in an end-to-end test and often disappear when engineers only inspect a catalog.

Record four baseline outcomes: the same item remains selected, the same source values are stored, every visible message follows the selected language or documented fallback, and each action produces the same verified result. Add layout observations at narrow and wide widths. These four outcomes can be checked after every translation update without requiring an entirely new test design.

Twenty-two implementation decisions for Textual Python terminal application

The following decisions move from translation boundaries to Textual’s widget state and Python gettext catalogs. They are deliberately sequenced so that a team can validate one working screen before expanding its language catalog. Do not confuse a working message lookup with a complete localization release.

1. Begin with a message inventory

Walk through every Textual Screen, modal, footer and notification. Record each literal shown to a librarian, the action it explains, and the screen where it appears.

Do not extract barcode values, patrons’ preferred names or free-text notes as if they were software messages. Harbor Library Desk, a fictional terminal application that helps librarians check borrowed books, reserve community rooms, and prepare multilingual visitor notices provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

A reliable place to start is the smallest working screen. Document what the operator believes the control means, the action it triggers, and the stored data it touches. That record gives a translator enough context to preserve intent rather than merely replacing individual words.

Test a loan renewal, an unavailable-room warning and a successful room booking as separate journeys. For a practical acceptance check, begin with the default-language interface, complete the named task, switch locale without restarting, and repeat it. Observe the new text but compare the same record identity, result state and output artifact. This is more informative than a static screenshot.

2. Define stable semantic keys

Use source-message identifiers or a consistent gettext msgid strategy that separates an action from its rendering. Include developer-facing context for ambiguous words such as hold, return and issue.

A short string without context can be wrongly translated as a noun instead of a command. Harbor Library Desk, a fictional terminal application that helps librarians check borrowed books, reserve community rooms, and prepare multilingual visitor notices provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Treat implementation and language review as two connected tests. A screen can compile yet mislead a user about whether a command merely started or actually completed. Write the expected state change before adjusting the visible copy, then verify both.

Make a reviewer read each key beside the screen and the action that follows it. To make the failure visible early, try one very short translation and one deliberately long one. Use a narrow terminal, keyboard-only input and a non-English script. If the control is clipped or its action changes, the implementation is not ready for release.

3. Choose catalog boundaries

Decide whether one gettext domain covers the whole app or whether independently shipped plugins have their own domains. Keep locale directories predictable and bundled.

A loaded library cannot find .mo files that were omitted from the installed package. Harbor Library Desk, a fictional terminal application that helps librarians check borrowed books, reserve community rooms, and prepare multilingual visitor notices provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

The difficult part is rarely finding a synonym. It is deciding which representation belongs to the interface and which is an unchanged fact. Make the distinction observable through a tiny example, a negative test, and a second language whose word order differs from English.

Inspect the installed wheel or executable rather than trusting the development source tree. A reviewer should see the whole interaction, not a detached spreadsheet cell. Present the source, its intended audience, the message context, placeholders and possible error states. Ask the reviewer what action they expect the system to perform from the translated wording.

4. Load translations explicitly

Create gettext.translation objects with a specified domain, localedir and ordered language preferences; keep a fallback policy visible in code.

Calling install globally can obscure which screen owns a choice and complicate multiple simultaneous sessions. Harbor Library Desk, a fictional terminal application that helps librarians check borrowed books, reserve community rooms, and prepare multilingual visitor notices provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Use a before-and-after run to prevent accidental side effects. Record selected item, user input, result code, terminal width and locale. If changing the language changes any unrelated record value, stop and repair the data boundary before polishing style.

Launch two sessions with different language preferences and confirm they do not unexpectedly share screen text. Record a passing and a failing path. The passing path tests fluency; the failure path tests truthfulness. An honest error must distinguish an unconfirmed operation from an operation completed and stored. This is especially important for irreversible or time-sensitive actions.

5. Separate locale from book data

Store patron IDs, reservation IDs, ISO-style machine timestamps and transaction statuses independent of interface strings. Translate only what staff see.

If a translated status label becomes the value stored in a database, later lookups may fail. Harbor Library Desk, a fictional terminal application that helps librarians check borrowed books, reserve community rooms, and prepare multilingual visitor notices provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Switch languages during a reservation and verify its ID and availability remain unchanged. For a practical acceptance check, begin with the default-language interface, complete the named task, switch locale without restarting, and repeat it. Observe the new text but compare the same record identity, result state and output artifact. This is more informative than a static screenshot.

6. Design a reactive language change

Maintain the chosen locale in app-level state and rebuild or update localized widget properties when it changes. Use Textual’s reactivity or explicit refresh logic as appropriate.

Changing a translator reference will not retroactively replace text already assigned to static Labels. Harbor Library Desk, a fictional terminal application that helps librarians check borrowed books, reserve community rooms, and prepare multilingual visitor notices provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Open a menu, change language, then inspect the menu, footer, modal and input placeholder. To make the failure visible early, try one very short translation and one deliberately long one. Use a narrow terminal, keyboard-only input and a non-English script. If the control is clipped or its action changes, the implementation is not ready for release.

7. Review compose-time strings

Understand which text appears when a widget is composed and which is generated on later events. Route both through the same translator.

A button created in compose may stay in the original language if only a status bar is updated. Harbor Library Desk, a fictional terminal application that helps librarians check borrowed books, reserve community rooms, and prepare multilingual visitor notices provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Test switching after navigating deeply, not just during the initial screen. A reviewer should see the whole interaction, not a detached spreadsheet cell. Present the source, its intended audience, the message context, placeholders and possible error states. Ask the reviewer what action they expect the system to perform from the translated wording.

8. Handle Rich formatting as data

Keep styling markup separate from translatable meaning when possible and allow translators to see placeholders in context. Escape user-supplied text before markup rendering.

A patron’s book title containing brackets must not accidentally become a Rich style instruction. Harbor Library Desk, a fictional terminal application that helps librarians check borrowed books, reserve community rooms, and prepare multilingual visitor notices provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Enter a title containing square brackets and check that it displays literally and safely. Record a passing and a failing path. The passing path tests fluency; the failure path tests truthfulness. An honest error must distinguish an unconfirmed operation from an operation completed and stored. This is especially important for irreversible or time-sensitive actions.

9. Respect width in terminal cells

Design responsive columns for CJK text, combining marks, accents and emoji; do not treat Python len as a visual measurement.

A supposedly short label may occupy two terminal columns per full-width character. Harbor Library Desk, a fictional terminal application that helps librarians check borrowed books, reserve community rooms, and prepare multilingual visitor notices provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Inspect 40-column and 80-column layouts with English, Japanese and Arabic samples. For a practical acceptance check, begin with the default-language interface, complete the named task, switch locale without restarting, and repeat it. Observe the new text but compare the same record identity, result state and output artifact. This is more informative than a static screenshot.

10. Use whole messages for plurals

Provide singular and plural source messages with ngettext and pass the actual count, rather than joining a number to English fragments.

The singular/plural logic in English does not apply to all languages or all count categories. Harbor Library Desk, a fictional terminal application that helps librarians check borrowed books, reserve community rooms, and prepare multilingual visitor notices provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Run counts zero, one, two, five and twenty-one in each target locale. To make the failure visible early, try one very short translation and one deliberately long one. Use a narrow terminal, keyboard-only input and a non-English script. If the control is clipped or its action changes, the implementation is not ready for release.

11. Localize dates at display boundaries

Keep stored timestamps structured and format them with deliberate locale and timezone rules, including clarity about appointment time zones.

Swapping month and day digits can send a visitor to the wrong booking date. Harbor Library Desk, a fictional terminal application that helps librarians check borrowed books, reserve community rooms, and prepare multilingual visitor notices provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Use a date with day greater than twelve plus a daylight-saving boundary case. A reviewer should see the whole interaction, not a detached spreadsheet cell. Present the source, its intended audience, the message context, placeholders and possible error states. Ask the reviewer what action they expect the system to perform from the translated wording.

12. Translate error outcomes accurately

Separate an unavailable service from a failed request, a completed booking and a retryable timeout. Messages must match actual system state.

A friendly translation that says saved when the database rejected a write is a serious trust problem. Harbor Library Desk, a fictional terminal application that helps librarians check borrowed books, reserve community rooms, and prepare multilingual visitor notices provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Simulate offline, server refusal and success; compare messages with the real transaction log. Record a passing and a failing path. The passing path tests fluency; the failure path tests truthfulness. An honest error must distinguish an unconfirmed operation from an operation completed and stored. This is especially important for irreversible or time-sensitive actions.

13. Preserve hotkeys and help

Keep actual key bindings in the input system and generate localized help from those bindings. A translated word is not a reason to silently move a shortcut.

Instructions may tell users to press a letter that no longer triggers the command. Harbor Library Desk, a fictional terminal application that helps librarians check borrowed books, reserve community rooms, and prepare multilingual visitor notices provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Compare footer hints with the keys accepted by the running screen. For a practical acceptance check, begin with the default-language interface, complete the named task, switch locale without restarting, and repeat it. Observe the new text but compare the same record identity, result state and output artifact. This is more informative than a static screenshot.

14. Protect input composition

Test text entry with non-Latin input methods, accented characters and pasted multilingual text. Do not assume that every key event is a printable character.

Filtering by ASCII ranges can reject a person’s real name or produce broken cursor navigation. Harbor Library Desk, a fictional terminal application that helps librarians check borrowed books, reserve community rooms, and prepare multilingual visitor notices provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Type, paste, backspace and edit Japanese, Hindi and French sample text. To make the failure visible early, try one very short translation and one deliberately long one. Use a narrow terminal, keyboard-only input and a non-English script. If the control is clipped or its action changes, the implementation is not ready for release.

15. Plan screen-reader alternatives

Consider whether an interactive terminal is usable through assistive technology and provide a clear non-interactive command or export when needed.

Correct translations do not by themselves guarantee assistive-technology access in a terminal. Harbor Library Desk, a fictional terminal application that helps librarians check borrowed books, reserve community rooms, and prepare multilingual visitor notices provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Test tab and keyboard progression and examine the plain-text equivalent of important results. A reviewer should see the whole interaction, not a detached spreadsheet cell. Present the source, its intended audience, the message context, placeholders and possible error states. Ask the reviewer what action they expect the system to perform from the translated wording.

16. Give notifications enough context

A toast or transient status message should describe the completed or blocked action, not merely say success or failed.

Fast disappearing messages make an unfamiliar language harder to check and can hide important details. Harbor Library Desk, a fictional terminal application that helps librarians check borrowed books, reserve community rooms, and prepare multilingual visitor notices provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Slow down and inspect messages after borrow, extend and cancel operations. Record a passing and a failing path. The passing path tests fluency; the failure path tests truthfulness. An honest error must distinguish an unconfirmed operation from an operation completed and stored. This is especially important for irreversible or time-sensitive actions.

17. Control fallback honestly

Choose a documented default locale; identify untranslated strings during testing and avoid giving users a falsely complete translation promise.

An unnoticed fallback may make one button English in an otherwise Spanish workflow. Harbor Library Desk, a fictional terminal application that helps librarians check borrowed books, reserve community rooms, and prepare multilingual visitor notices provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Deliberately remove one test key and confirm logging, display and review behavior. For a practical acceptance check, begin with the default-language interface, complete the named task, switch locale without restarting, and repeat it. Observe the new text but compare the same record identity, result state and output artifact. This is more informative than a static screenshot.

18. Review user-owned strings safely

Book titles and visitor comments may appear next to interface labels, but they are data, not keys in the gettext catalog.

Untrusted strings must not be evaluated as Rich markup or interpolated as format directives. Harbor Library Desk, a fictional terminal application that helps librarians check borrowed books, reserve community rooms, and prepare multilingual visitor notices provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Use punctuation, braces, brackets and right-to-left samples in user fields. To make the failure visible early, try one very short translation and one deliberately long one. Use a narrow terminal, keyboard-only input and a non-English script. If the control is clipped or its action changes, the implementation is not ready for release.

19. Package locale assets with releases

Test editable installation, regular wheel, zipped build and any desktop packaging method separately. .po files are review sources and .mo files are compiled runtime assets.

A file path that works from a repository may fail inside a packaged distribution. Harbor Library Desk, a fictional terminal application that helps librarians check borrowed books, reserve community rooms, and prepare multilingual visitor notices provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Install the artifact into a clean environment with no source checkout. A reviewer should see the whole interaction, not a detached spreadsheet cell. Present the source, its intended audience, the message context, placeholders and possible error states. Ask the reviewer what action they expect the system to perform from the translated wording.

20. Automate critical locale journeys

Use Textual’s testing facilities where suitable for screen actions and snapshots, then complement automation with a human language review.

A passing event test can still miss unnatural translation or visual clipping. Harbor Library Desk, a fictional terminal application that helps librarians check borrowed books, reserve community rooms, and prepare multilingual visitor notices provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Capture labels, focused control, action outcome and terminal width as distinct assertions. Record a passing and a failing path. The passing path tests fluency; the failure path tests truthfulness. An honest error must distinguish an unconfirmed operation from an operation completed and stored. This is especially important for irreversible or time-sensitive actions.

21. Design rollback without data changes

Keep language changes and catalog releases reversible. A bad catalog should not require rewriting loans or reservations.

A release rollback can fail if translated values were stored as application state. Harbor Library Desk, a fictional terminal application that helps librarians check borrowed books, reserve community rooms, and prepare multilingual visitor notices provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Restore the previous catalog and replay an existing reservation record. For a practical acceptance check, begin with the default-language interface, complete the named task, switch locale without restarting, and repeat it. Observe the new text but compare the same record identity, result state and output artifact. This is more informative than a static screenshot.

22. Publish only verified coverage

List supported locales and known terminal limitations in release notes. Be precise about partial support and platform variations.

A locale is not supported merely because a catalog file exists. Harbor Library Desk, a fictional terminal application that helps librarians check borrowed books, reserve community rooms, and prepare multilingual visitor notices provides a useful test bed because staff encounter translated prose beside operational records and must still be able to trust both.

Run real actions in every promised language on supported terminals before publishing. To make the failure visible early, try one very short translation and one deliberately long one. Use a narrow terminal, keyboard-only input and a non-English script. If the control is clipped or its action changes, the implementation is not ready for release.

Worked implementation: from an English screen to a maintained multilingual release

Phase A: record the baseline

Capture the current source-language screen, data IDs, key bindings and normal end state. Save a simple acceptance transcript showing what a correct interaction looks like. A second person should be able to follow it without knowing the source code. For Harbor Library Desk, a fictional terminal application that helps librarians check borrowed books, reserve community rooms, and prepare multilingual visitor notices, compare the localized interface with the unchanged underlying task record and keep a clear note of what was verified.

Phase B: design the catalog

Give each visible sentence a clear purpose and stable context. Capture variable names and units. Use complete messages for counts and conditions; do not ask translators to guess whether a word is a verb, a noun or a hidden system state. For Harbor Library Desk, a fictional terminal application that helps librarians check borrowed books, reserve community rooms, and prepare multilingual visitor notices, compare the localized interface with the unchanged underlying task record and keep a clear note of what was verified.

Phase C: introduce locale state

Give language preference a clear owner. Render a complete screen in a target language, then change back while preserving input, selection and identity. If a widget keeps stale wording, update the appropriate state rather than rewriting stored data. For Harbor Library Desk, a fictional terminal application that helps librarians check borrowed books, reserve community rooms, and prepare multilingual visitor notices, compare the localized interface with the unchanged underlying task record and keep a clear note of what was verified.

Phase D: challenge the layout

Test 40-column and 80-column arrangements, realistic line wrapping, full-width characters, long translated labels and minimal-colour terminals. A terminal interface must survive these constraints even when every string is grammatically correct. For Harbor Library Desk, a fictional terminal application that helps librarians check borrowed books, reserve community rooms, and prepare multilingual visitor notices, compare the localized interface with the unchanged underlying task record and keep a clear note of what was verified.

Phase E: test error truthfulness

Cause a safe simulated failure and check which message appears. Do not say an export succeeded until the artifact exists. Do not say an upload was accepted until acknowledgment is confirmed. Capture the result code separately from its human-language explanation. For Harbor Library Desk, a fictional terminal application that helps librarians check borrowed books, reserve community rooms, and prepare multilingual visitor notices, compare the localized interface with the unchanged underlying task record and keep a clear note of what was verified.

Phase F: test installation and language coverage

Install the actual distributable in a clean environment. Check that translation resources are available offline, that unsupported language preferences fall back predictably, and that every claimed supported language completes the same user journey. For Harbor Library Desk, a fictional terminal application that helps librarians check borrowed books, reserve community rooms, and prepare multilingual visitor notices, compare the localized interface with the unchanged underlying task record and keep a clear note of what was verified.

Twenty-four real troubleshooting situations

A useful localization problem report includes the requested language, catalog version, executable version, terminal emulator, window dimensions, input method, triggering action and observed result. Without these details, a one-line report such as translation broken is too vague to reproduce. The cases below show where to look and how to prove the repair.

Case 1: English remains in a modal

The modal was built with a literal instead of the translator. First reproduce the failure with a known catalog, a fixed terminal width and a record whose identifier can be inspected afterward. Write down the visible message and the actual state transition: those two observations tell you whether the fault is in language lookup, layout or application behavior.

Find the modal constructor and make its title and buttons resolve through the selected locale; reopen the dialog and switch languages while it is visible. After the repair, restart the installed application, use keyboard input to trigger the same screen, and compare the saved result with its original identifier. The target-language message must describe the observed state and must remain readable when the terminal is resized.

Case 2: MO file not found on another machine

The build excluded the compiled catalog or changed the locale directory. Isolate one variable at a time. Try the default language and a target language under the same input and terminal conditions; then change just the terminal width or packaged runtime. This prevents a packaging failure being mistaken for a grammar error.

Inspect package manifest and runtime localedir, then add a smoke test using an installed artifact. Acceptance means more than eliminating the screenshot defect. Ask a reader fluent in that language to explain the message and then perform the intended action without coaching. Confirm that nothing in the exported record changes solely because the interface language changed.

Case 3: A book title renders as markup

Rich-compatible rendering interpreted brackets from untrusted data. Treat the visible symptom as evidence, not as a reason to alter stored data. Inspect how the message was produced, what version of the library was installed, and whether the event completed before the interface made its claim.

Escape or render user text as literal data while retaining trusted application styling. Retest with an intentionally long translation and a non-Latin test value. Also check whether the error stays visible long enough to understand. If a translated warning disappears before the user can respond, the problem is only partly fixed.

Case 4: The footer shortcut is incorrect

The help label was translated independently from the binding map. Create a regression test for the particular case before editing the translation. Include an unsuccessful path where one is possible; many serious localization defects occur in error screens that receive little attention during normal use.

Generate hints from the actual binding and test key presses in each locale. Finally, test both a fresh installation and the normal developer environment. Packaging, font, catalog and terminal settings often hide failures during development. Keep the exact reproducer in the release checklist so the next upgrade cannot silently restore it.

Case 5: A long translation hides the reserve button

The horizontal layout assumed English character widths. First reproduce the failure with a known catalog, a fixed terminal width and a record whose identifier can be inspected afterward. Write down the visible message and the actual state transition: those two observations tell you whether the fault is in language lookup, layout or application behavior.

Use flexible containers, minimum widths and wrapping; inspect narrow terminals. After the repair, restart the installed application, use keyboard input to trigger the same screen, and compare the saved result with its original identifier. The target-language message must describe the observed state and must remain readable when the terminal is resized.

Case 6: A Japanese input candidate disappears

Keystroke handling or an input widget path mishandles composition. Isolate one variable at a time. Try the default language and a target language under the same input and terminal conditions; then change just the terminal width or packaged runtime. This prevents a packaging failure being mistaken for a grammar error.

Reproduce with the actual IME and check the supported widget input events before changing key filters. Acceptance means more than eliminating the screenshot defect. Ask a reader fluent in that language to explain the message and then perform the intended action without coaching. Confirm that nothing in the exported record changes solely because the interface language changed.

Case 7: A patron’s name changes after language switch

Display conversion was accidentally applied to stored profile data. Treat the visible symptom as evidence, not as a reason to alter stored data. Inspect how the message was produced, what version of the library was installed, and whether the event completed before the interface made its claim.

Keep names untouched and translate only surrounding field labels. Retest with an intentionally long translation and a non-Latin test value. Also check whether the error stays visible long enough to understand. If a translated warning disappears before the user can respond, the problem is only partly fixed.

Case 8: A localized date points to the wrong day

The formatter used default regional conventions without recording timezone. Create a regression test for the particular case before editing the translation. Include an unsuccessful path where one is possible; many serious localization defects occur in error screens that receive little attention during normal use.

Track timestamp, user locale and timezone separately and compare with the canonical booking. Finally, test both a fresh installation and the normal developer environment. Packaging, font, catalog and terminal settings often hide failures during development. Keep the exact reproducer in the release checklist so the next upgrade cannot silently restore it.

Case 9: Plural copy is wrong for zero

The catalog supplies an English-centric singular or plural decision. First reproduce the failure with a known catalog, a fixed terminal width and a record whose identifier can be inspected afterward. Write down the visible message and the actual state transition: those two observations tell you whether the fault is in language lookup, layout or application behavior.

Use ngettext and review target-language rules with varied counts. After the repair, restart the installed application, use keyboard input to trigger the same screen, and compare the saved result with its original identifier. The target-language message must describe the observed state and must remain readable when the terminal is resized.

Case 10: Two staff sessions share one language

A process-global translator object was mutated for every user. Isolate one variable at a time. Try the default language and a target language under the same input and terminal conditions; then change just the terminal width or packaged runtime. This prevents a packaging failure being mistaken for a grammar error.

Scope language choice and translator lookup to the session or app instance. Acceptance means more than eliminating the screenshot defect. Ask a reader fluent in that language to explain the message and then perform the intended action without coaching. Confirm that nothing in the exported record changes solely because the interface language changed.

Case 11: Language switch resets the form

The screen is recreated without preserving input state. Treat the visible symptom as evidence, not as a reason to alter stored data. Inspect how the message was produced, what version of the library was installed, and whether the event completed before the interface made its claim.

Save semantic form values in stable state, then update presentation without wiping fields. Retest with an intentionally long translation and a non-Latin test value. Also check whether the error stays visible long enough to understand. If a translated warning disappears before the user can respond, the problem is only partly fixed.

Case 12: A reservation error claims completion

Translation was chosen based on request sent rather than response confirmed. Create a regression test for the particular case before editing the translation. Include an unsuccessful path where one is possible; many serious localization defects occur in error screens that receive little attention during normal use.

Map messages to actual result codes and preserve uncertain outcomes. Finally, test both a fresh installation and the normal developer environment. Packaging, font, catalog and terminal settings often hide failures during development. Keep the exact reproducer in the release checklist so the next upgrade cannot silently restore it.

Case 13: Missing translation appears as a key

Fallback was disabled or no source message exists. First reproduce the failure with a known catalog, a fixed terminal width and a record whose identifier can be inspected afterward. Write down the visible message and the actual state transition: those two observations tell you whether the fault is in language lookup, layout or application behavior.

Use a documented fallback and surface missing-key diagnostics to reviewers. After the repair, restart the installed application, use keyboard input to trigger the same screen, and compare the saved result with its original identifier. The target-language message must describe the observed state and must remain readable when the terminal is resized.

Case 14: Colours indicate success without words

Status icons were not paired with translated text. Isolate one variable at a time. Try the default language and a target language under the same input and terminal conditions; then change just the terminal width or packaged runtime. This prevents a packaging failure being mistaken for a grammar error.

Write accessible status messages that explain the result independently of colour. Acceptance means more than eliminating the screenshot defect. Ask a reader fluent in that language to explain the message and then perform the intended action without coaching. Confirm that nothing in the exported record changes solely because the interface language changed.

Case 15: A popup moves outside the screen

Localized label length changed widget dimensions. Treat the visible symptom as evidence, not as a reason to alter stored data. Inspect how the message was produced, what version of the library was installed, and whether the event completed before the interface made its claim.

Retest positioning and available width at the smallest supported terminal size. Retest with an intentionally long translation and a non-Latin test value. Also check whether the error stays visible long enough to understand. If a translated warning disappears before the user can respond, the problem is only partly fixed.

Case 16: Keyboard focus jumps after switching language

Widgets were destroyed and recreated without restoring focus. Create a regression test for the particular case before editing the translation. Include an unsuccessful path where one is possible; many serious localization defects occur in error screens that receive little attention during normal use.

Keep stable widget identities or explicitly restore the previously focused control. Finally, test both a fresh installation and the normal developer environment. Packaging, font, catalog and terminal settings often hide failures during development. Keep the exact reproducer in the release checklist so the next upgrade cannot silently restore it.

Case 17: A printed report contains untranslated headings

Export logic bypassed UI gettext functions. First reproduce the failure with a known catalog, a fixed terminal width and a record whose identifier can be inspected afterward. Write down the visible message and the actual state transition: those two observations tell you whether the fault is in language lookup, layout or application behavior.

Route report labels through the same catalog policy and test file output. After the repair, restart the installed application, use keyboard input to trigger the same screen, and compare the saved result with its original identifier. The target-language message must describe the observed state and must remain readable when the terminal is resized.

Case 18: RTL content is visually reordered unexpectedly

Terminal rendering and font shaping differ from a browser’s bidi engine. Isolate one variable at a time. Try the default language and a target language under the same input and terminal conditions; then change just the terminal width or packaged runtime. This prevents a packaging failure being mistaken for a grammar error.

Test actual terminal combinations, document limitations and offer an accessible alternative. Acceptance means more than eliminating the screenshot defect. Ask a reader fluent in that language to explain the message and then perform the intended action without coaching. Confirm that nothing in the exported record changes solely because the interface language changed.

Case 19: An error includes an untranslated Python exception

Low-level exception text was shown to users directly. Treat the visible symptom as evidence, not as a reason to alter stored data. Inspect how the message was produced, what version of the library was installed, and whether the event completed before the interface made its claim.

Map known conditions to localizable explanations and keep raw diagnostics in logs. Retest with an intentionally long translation and a non-Latin test value. Also check whether the error stays visible long enough to understand. If a translated warning disappears before the user can respond, the problem is only partly fixed.

Case 20: A quote mark breaks interpolation

A message was concatenated or formatted using unsafe delimiters. Create a regression test for the particular case before editing the translation. Include an unsuccessful path where one is possible; many serious localization defects occur in error screens that receive little attention during normal use.

Use structured placeholders with a validated formatting contract and test embedded punctuation. Finally, test both a fresh installation and the normal developer environment. Packaging, font, catalog and terminal settings often hide failures during development. Keep the exact reproducer in the release checklist so the next upgrade cannot silently restore it.

Case 21: Help text describes an old feature

Translation review did not track behavior changes. First reproduce the failure with a known catalog, a fixed terminal width and a record whose identifier can be inspected afterward. Write down the visible message and the actual state transition: those two observations tell you whether the fault is in language lookup, layout or application behavior.

Treat UI changes as message-review triggers and compare catalogs with current screens. After the repair, restart the installed application, use keyboard input to trigger the same screen, and compare the saved result with its original identifier. The target-language message must describe the observed state and must remain readable when the terminal is resized.

Case 22: A test passes only in the developer locale

Tests rely on environment variables and filesystem layout. Isolate one variable at a time. Try the default language and a target language under the same input and terminal conditions; then change just the terminal width or packaged runtime. This prevents a packaging failure being mistaken for a grammar error.

Set language and paths explicitly in tests and exercise clean installations. Acceptance means more than eliminating the screenshot defect. Ask a reader fluent in that language to explain the message and then perform the intended action without coaching. Confirm that nothing in the exported record changes solely because the interface language changed.

Case 23: Locale fallback changes after OS update

Default environment detection selected a different language. Treat the visible symptom as evidence, not as a reason to alter stored data. Inspect how the message was produced, what version of the library was installed, and whether the event completed before the interface made its claim.

Make precedence explicit and allow a persisted user preference to win. Retest with an intentionally long translation and a non-Latin test value. Also check whether the error stays visible long enough to understand. If a translated warning disappears before the user can respond, the problem is only partly fixed.

Case 24: A multi-line warning is cut off

A transient widget has a fixed height inappropriate for expanded text. Create a regression test for the particular case before editing the translation. Include an unsuccessful path where one is possible; many serious localization defects occur in error screens that receive little attention during normal use.

Provide wrapping and a readable detailed view for consequential warnings. Finally, test both a fresh installation and the normal developer environment. Packaging, font, catalog and terminal settings often hide failures during development. Keep the exact reproducer in the release checklist so the next upgrade cannot silently restore it.

A four-week implementation and release plan

Week 1 — scope and preserve behavior

Identify supported locales and complete user journeys. Inventory every visible message and every record that must remain unchanged. Pin exact dependencies. Build one minimal lookup in two languages and capture a baseline test for keyboard actions, storage and terminal size.

Deliverable: a message inventory, a record protection map, working language selection and one reproducible test. A schedule is useful only if the evidence is retained and rechecked when libraries or catalogs change.

Week 2 — complete the critical messages

Translate the primary navigation, confirmation, input guidance, warning and failure pathways. Add grammar-aware count messages and deliberate date and number formatting. Run an in-context review of every action that changes a record, including cancel and retry.

Deliverable: coherent main-task screens, reviewed placeholders and explicit fallback behavior. A schedule is useful only if the evidence is retained and rechecked when libraries or catalogs change.

Week 3 — layout, accessibility and installation

Exercise narrow terminals, wide-character scripts, paste, focus, keyboard navigation, missing assets, monochrome display and redirected output. Install a release build in a clean environment and run it with no access to development directories.

Deliverable: a regression report with actual terminal and platform details, plus a corrected release artifact. A schedule is useful only if the evidence is retained and rechecked when libraries or catalogs change.

Week 4 — validate and communicate support

Ask fluent readers to complete the same real task in each supported language without coaching. Check stored IDs, results, export fields and error semantics after every run. Document unsupported terminals, partial locales and rollback procedure without overstating coverage.

Deliverable: release sign-off for tested language-platform combinations and a repeatable update checklist. A schedule is useful only if the evidence is retained and rechecked when libraries or catalogs change.

Frequently asked questions

Does Textual automatically translate widgets?

No. Textual manages interactive UI; a separate message lookup and catalog strategy supplies target-language strings. In practical terms, start with a complete user action rather than an isolated string. Verify the visible result, the underlying state and the actual languages promised. Where a terminal or dependency version changes behavior, follow the linked official documentation for that installed release.

Is Python gettext appropriate?

Yes for conventional message catalogs; use translation objects and explicit fallback rather than assuming one global language. In practical terms, start with a complete user action rather than an isolated string. Verify the visible result, the underlying state and the actual languages promised. Where a terminal or dependency version changes behavior, follow the linked official documentation for that installed release.

Must every book title be translated?

No. Stored titles are bibliographic data. Where an authorized edition has a translated title, handle that as a data record with provenance. In practical terms, start with a complete user action rather than an isolated string. Verify the visible result, the underlying state and the actual languages promised. Where a terminal or dependency version changes behavior, follow the linked official documentation for that installed release.

What is the role of .po and .mo?

PO files are editable translation catalogs; MO files are compiled catalog artifacts often loaded at runtime by gettext. In practical terms, start with a complete user action rather than an isolated string. Verify the visible result, the underlying state and the actual languages promised. Where a terminal or dependency version changes behavior, follow the linked official documentation for that installed release.

Can language change without restart?

It can when the app updates existing widget labels or reconstructs them while preserving application state. In practical terms, start with a complete user action rather than an isolated string. Verify the visible result, the underlying state and the actual languages promised. Where a terminal or dependency version changes behavior, follow the linked official documentation for that installed release.

Can I translate keyboard shortcuts?

Translate the help text; change bindings only deliberately and make the displayed shortcut agree with the actual action. In practical terms, start with a complete user action rather than an isolated string. Verify the visible result, the underlying state and the actual languages promised. Where a terminal or dependency version changes behavior, follow the linked official documentation for that installed release.

Why does Japanese text need more space?

Terminal cell width and grapheme behavior differ from the number of Python characters or bytes. In practical terms, start with a complete user action rather than an isolated string. Verify the visible result, the underlying state and the actual languages promised. Where a terminal or dependency version changes behavior, follow the linked official documentation for that installed release.

How should errors be translated?

Map stable error conditions to messages; never translate a failed operation into a claimed success. In practical terms, start with a complete user action rather than an isolated string. Verify the visible result, the underlying state and the actual languages promised. Where a terminal or dependency version changes behavior, follow the linked official documentation for that installed release.

Will browser and terminal rendering match?

Not necessarily. Textual’s supported front ends and real terminals have different input and display behavior. In practical terms, start with a complete user action rather than an isolated string. Verify the visible result, the underlying state and the actual languages promised. Where a terminal or dependency version changes behavior, follow the linked official documentation for that installed release.

How do I check a new catalog?

Compile it, launch a clean app, walk through key tasks and have a fluent reviewer assess meaning. In practical terms, start with a complete user action rather than an isolated string. Verify the visible result, the underlying state and the actual languages promised. Where a terminal or dependency version changes behavior, follow the linked official documentation for that installed release.

What if a language is incomplete?

Use a clear fallback, record missing entries and avoid calling the edition complete. In practical terms, start with a complete user action rather than an isolated string. Verify the visible result, the underlying state and the actual languages promised. Where a terminal or dependency version changes behavior, follow the linked official documentation for that installed release.

What matters most before shipping?

Real workflow outcomes, missing assets, keyboard behavior, narrow layouts, script entry and safe data boundaries. In practical terms, start with a complete user action rather than an isolated string. Verify the visible result, the underlying state and the actual languages promised. Where a terminal or dependency version changes behavior, follow the linked official documentation for that installed release.

Official documentation and further reading

Library interfaces and compatibility can evolve. Read the current primary documentation and pin the version used by your project; do not assume that an example from a different major version remains correct. Terminal fonts, input systems and screen readers also differ across platforms, so document the actual environments tested.

Continue learning about translation quality

This guide is a platform-specific implementation reference, not a substitute for general research into meaning, register, uncertainty, culture and translation ethics. For that broader foundation, use the translation master. For other technical environments, follow the series index and choose a guide matching your own toolkit.

Master Art of Translation · Translate Like a Pro series index · Longform organization reference · Previous reserved-tens article

Translate Like a Pro | 7390 — Textual Python TUI Localization, Gettext Catalogs, Reactive Widgets, Keyboard Input and Release QA