How do you translate a Qt 6 application that mixes QML screens with C++ logic without missing messages, shipping stale QM files or breaking a language switch? This Qt localization guide explains qsTr, QTranslator, lupdate, lrelease, CMake translation integration, and real release testing for multilingual desktop software. It is designed for developers and translation reviewers who need the final installed experience to match what the application actually does.
Qt Quick and Qt C++ use the same broad TS and QM translation workflow. lupdate extracts translatable source messages and updates translation source catalogs; lrelease creates compact QM catalogs for runtime lookup. That technical path is necessary but not sufficient. Translators need the right context, the app needs the right language lifecycle, and every displayed status must remain consistent with underlying data.
Imagine an international warehouse-inventory tool with a QML dashboard, C++ stock services and several local field offices. A user scans pallet BX-2409, requests a transfer, sees a pending approval and exports a French packing list while working in Arabic. The guide follows that work from resource extraction to language selection, data formatting, accessibility, packaging, regression testing and audit-friendly release evidence.
Quick route: what to do first
First establish which texts and assets belong to your application; second define supported languages and a reliable fallback; third connect translated resources to the real product build; fourth test the complete user task while checking invariant data. Do not begin by counting strings alone. A translation is good when the person using the software understands the action, consequence and available recovery path in their own language.
How this guide is organised
The first part explains the platform’s message and asset system. The middle part follows a realistic task across language changes, errors and documents. The practical cases distinguish what a reader sees, where the problem originates, how to correct it and what would count as evidence. The final section gives a release checklist, answers common questions and points to authoritative technical documentation.
Quick answer: translate the presentation, preserve the inventory state
Mark application-owned text with the correct QML or C++ translation mechanism and provide catalogs for each supported language. Make the build extract and compile catalogs, load the desired language in the application and rebuild or re-evaluate affected views when language changes. Inventory IDs, quantities, warehouse codes and approval flags remain language-independent. A translation must not make a pending transfer appear accepted; the localized interface is one view over a stable operational record.
Know which layer owns each string
QML views, reusable components, C++ service code, exception mapping, system dialogs, generated reports and external modules do not necessarily share the same source or resource lifetime. Inventory visible strings before extraction. Use qsTr for appropriate QML source text and Qt’s translation patterns for C++ messages; use context or IDs where appropriate. Avoid building sentences from multiple little translated fragments. A grammar may need a different order or plural form; the translation unit should contain enough meaning.
Use lupdate and lrelease as distinct build stages
lupdate searches supported source files and updates TS translation catalogs. lrelease transforms reviewed TS catalogs into QM files used by the application. Updating source code without rerunning extraction leaves new strings unavailable to translators. Releasing without recompiling catalogs ships old wording. Qt documents translations through CMake as well as other supported project build systems. Keep source inventory and output packaging under revision control and inspect build warnings before delivering binaries.
Set up CMake translations deliberately
Modern Qt CMake translation helpers can associate translation sources with application targets, but the exact helper and arguments depend on the Qt version and build architecture. Follow the matching official documentation, specify all relevant QML and C++ source roots and confirm that the build invokes the expected translation updates and compilation. Generated outputs are not necessarily placed where deployed applications will look for them. A reproducible release must prove both successful catalog generation and runtime discovery.
Understand QTranslator lifetime and QML refresh
QTranslator provides runtime translated lookup through installed translation resources. Changing a translator or selected language does not automatically guarantee that every property in every C++ object and every custom QML binding refreshes in a hybrid application. Decide how the app re-evaluates translated QML expressions and updates imperative C++ labels, dialogs or model-generated text. Preserve unsaved stock edits through the operation. Test switching when the app is mid-task, not only while its settings page is open.
Plural grammar, identifiers and placeholders
A warehouse message may describe one damaged item, two damaged items or hundreds of them. Qt’s translation facilities support count-dependent messages when written appropriately; translating ‘items’ in isolation is rarely enough. Validate positional arguments and translation context. Treat an inventory reference such as BX-2409 as a typed identifier, not an ordinary phrase to reorder or translate. Numeric quantities, units and currencies should be formatted for the viewer without corrupting their stored value.
Images, dates, bidirectionality and accessible controls
QML layouts can resize or reflow to accommodate longer target-language strings. Mirror navigation intentionally for right-to-left interfaces, but do not mirror brand marks, charts or stock identifiers without review. Check keyboard focus, screen-reader properties, validation guidance and control touch targets. Date and time presentations require an explicit time zone for cross-border workflows. A physical delivery date is not changed because a user selects another interface locale.
Distinguish Qt module text from your own text
A running app may show built-in Qt module controls and application-owned screens. Module translations can have their own catalogs and packaging needs. Inspect file pickers, print previews, media dialogs and error surfaces rather than assuming everything comes from one catalog. If the operating system owns a dialog, communicate that limitation. The goal is a truthful explanation of the user’s task rather than an unsupported claim of universal translation coverage.
Follow an approval journey across languages
A warehouse clerk in Arabic creates a transfer of six units, a supervisor in German reviews it, and a customer receives a French packing list. Each view contains different reader-facing language while the transfer ID, quantity, item SKU and approval state remain constant. If a scanner times out, a visible notice must distinguish ‘not scanned’, ‘scan saved locally’ and ‘accepted by warehouse service’. Test each status by creating the underlying condition, not by screenshotting a mocked label.
Release through a locale and build matrix
Include QML assets, source-generated TS updates, finished QM catalogs and Qt module language resources as applicable in the actual distributable. Smoke-test clean installation, upgrades and multiple OS language preferences. Compare translated menus, QML charts, C++ exceptions, printed documents, accessibility and right-to-left layouts. Record app version, catalog checksum, locale, workflow step and verified data state. A reproducible failed-case test is more valuable than a gallery of attractive translated screens.
Practical translation and localization situations
The following 39 cases are deliberately different. They are realistic failure patterns to test, not claims that Qt inherently contains each defect. For every case keep the underlying action fixed, reproduce the user-visible problem, trace the responsible resource or state, apply a precise correction and rerun the test in a delivered build. This separates technical loading failures from genuine translation misunderstandings.
1. QML source omitted from extraction
What the reader experiences. A new warehouse screen stays English while the C++ menu is translated. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. The QML source directory was not included in lupdate inputs. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Add the source to translation targets and regenerate TS catalogs. Then confirm the new page string appears in the reviewed catalog. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
2. C++ service message never marked
What the reader experiences. An inventory conflict is shown as raw English diagnostic text. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. Service-layer messages bypass translation functions and context. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Map the status to a translatable user message with parameters. Then induce a stock collision and compare the exact message. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
3. TS updated but QM stale
What the reader experiences. A corrected German label appears in Linguist yet not in the installed app. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. lrelease did not run after translators finished the TS entry. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Compile catalogs and copy current QM artifacts into the package. Then check installed catalog hash against the build. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
4. QM missing from bundle
What the reader experiences. Language selection works on the test machine but not the release machine. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. Deployment omitted a translation output directory. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Include compiled catalogs in the platform deployment manifest. Then install onto a clean account with no build tree. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
5. Wrong translator load order
What the reader experiences. Some views use Spanish while others fall back to English. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. The application creates controls before its intended QTranslator is ready. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Install appropriate translators before constructing visible UI. Then cold-start into Spanish and inspect first-run dialogs. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
6. App catalog conflicts with module catalog
What the reader experiences. A Qt-provided dialog ignores the language configured for the application. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. Framework module translations have separate resource ownership. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Identify required module catalogs and load or deploy them correctly. Then test standard dialogs next to application-owned dialogs. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
7. QML qsTr not evaluated on switch
What the reader experiences. The dashboard heading changes only after navigating away. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. A translated binding is not properly re-evaluated after language change. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Implement documented QML retranslation behavior for chosen Qt version. Then switch languages while remaining on the same active screen. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
8. Imperative C++ label remains old
What the reader experiences. A C++-created notification keeps French after QML switches to Arabic. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. Its display text was assigned once during construction. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Reconnect update events to explicit label regeneration. Then trigger the notice before and after the switch. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
9. Unsaved form discarded on rebuild
What the reader experiences. A half-completed transfer disappears when a language selector is used. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. The app rebuilds QML roots without retaining draft state. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Keep draft models independent of view recreation. Then enter a unique note and switch languages twice. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
10. Placeholder ordering corrupts meaning
What the reader experiences. A Spanish alert assigns quantity to the SKU placeholder. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. Translation arguments are reordered or mismatched. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Review and test numbered arguments with distinctive dummy values. Then render an alert for SKU BX-2409 and quantity six. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
11. Count grammar wrong
What the reader experiences. A message reports one damaged carton with unnatural plural wording. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. A concatenated source string cannot express target plural rules. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Use Qt count-aware translation support for the complete sentence. Then test zero, one, two and several dozen items. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
12. Scanner code accidentally translated
What the reader experiences. A pallet ID displayed to a colleague no longer matches its barcode. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. The identifier was passed through translation lookup as prose. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Keep IDs immutable and insert them only as typed parameters. Then scan and rescan the same pallet across locales. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
13. Right-to-left number appears reversed
What the reader experiences. A transfer code is displayed in visually confusing order in Arabic. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. Mixed-directional text is not isolated in the interface. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Review bidirectional handling and identifier presentation. Then have a native reader copy the exact code. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
14. Long warehouse name pushes action offscreen
What the reader experiences. A German phrase makes the approval control impossible to tap. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. The layout assumes English label lengths and fixed widths. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Allow wrapping or repositioning while preserving priority actions. Then complete approval with large text and narrow viewport. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
15. Date changes its meaning after switch
What the reader experiences. 03/04 is read as a different calendar date in another region. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. The UI stores formatted strings rather than typed dates. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Persist structured dates and format them at display time. Then compare the database value through two locale switches. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
16. Time zone omitted from cutoff
What the reader experiences. Two offices interpret a shipment deadline differently. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. The app shows an unqualified local clock value. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Display the relevant business time zone with deadlines. Then compare a single deadline across both offices. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
17. Validation message untranslated
What the reader experiences. A required address field shows raw English after French form submission. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. Validation lives in a model helper not included in catalogs. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Add all user-facing validation messages to translation extraction. Then submit invalid shipping details in each locale. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
18. Contextless Open label
What the reader experiences. Open is translated as an adjective rather than a command. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. The source string does not explain UI context. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Use meaningful contexts and translator notes. Then native reviewers open and close the same pallet panel. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
19. Capitalization change invalidates lookup
What the reader experiences. An edited source phrase falls back to English in one build. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. Source-text identity changed without catalog refresh. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Run lupdate, review message changes and recompile. Then exercise the exact newly edited label. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
20. Translator marked entry unfinished
What the reader experiences. An Italian-like test catalog appears complete in editor but ships fallback text. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. lrelease includes finished entries according to translation status. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Review finished flags and release coverage by key. Then inspect the compiled output through actual runtime lookup. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
21. CMake target excludes generated file
What the reader experiences. The translation asset builds in one configuration but not another. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. Release and debug translation targets differ. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Apply version-appropriate Qt CMake translation target configuration. Then build both configurations from clean checkout. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
22. QML text assembled from fragments
What the reader experiences. The phrase ‘Transfer to warehouse’ has unnatural target word order. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. Sentence pieces are translated separately and concatenated. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Translate complete meaning-bearing sentences with named context. Then review target examples with different destination names. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
23. Different word for hold
What the reader experiences. The UI confuses holding a pallet with putting a request on hold. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. One ambiguous key serves two separate domain actions. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Separate keys and add translator guidance about each action. Then test the physical handling and approval actions independently. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
24. Language preference ignored on reboot
What the reader experiences. A user selects German but launches in English next day. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. Locale selection is transient rather than stored product preference. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Persist supported language code separately from OS defaults. Then restart the app and confirm the selected language. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
25. System locale unexpectedly overrides manual choice
What the reader experiences. An Arabic-speaking operator sees French after changing OS settings. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. Startup selection prioritizes OS language over user preference. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Document and enforce the selected precedence rule. Then change OS language and relaunch with saved preference. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
26. Nonexistent regional catalog requested
What the reader experiences. The app fails when selecting es-MX though only es exists. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. Region fallback behavior is not designed or verified. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Define intended locale fallback and test catalog resolution. Then request unsupported region and inspect visible fallback. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
27. An imported plugin ships older messages
What the reader experiences. Inventory add-on dialogs mention controls no longer in the product. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. Plugin catalog and host binaries have different versions. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Version plugin resources and check host compatibility. Then enable add-on on upgrade and complete a task. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
28. QML chart legend is not translated
What the reader experiences. A graph uses source-language status names while toolbar is localized. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. Legend strings are generated from domain data without display mapping. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Map status enum to localized labels while keeping enum stable. Then compare graph grouping before and after language switch. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
29. High-contrast icon label missing
What the reader experiences. An icon-only approval control is unclear to keyboard and screen-reader users. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. Accessible properties were not included in text inventory. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Localize accessible names and test focus indicators. Then approve via keyboard with assistive technology. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
30. Translated Delete masks irreversible action
What the reader experiences. A confirmation becomes too vague about removing inventory history. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. Translator lacks context about consequence and permission. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Use explicit wording and supply deletion semantics to reviewer. Then run deletion in a test environment and verify informed consent. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
31. A local warning claims sync success
What the reader experiences. A network timeout message says stock has been updated. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. The localized result conflates local save and server commit. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Separate queued, sent, acknowledged and failed statuses. Then block network and observe actual state messages. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
32. Packing list uses interface language
What the reader experiences. An overseas customer receives an Arabic document instead of French. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. Export language inherits current UI locale automatically. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Add explicit document-locale choice and preview. Then export same inventory record twice and compare data integrity. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
33. Printed fonts omit characters
What the reader experiences. Cyrillic or accented letters become empty boxes in release PDF. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. The export font lacks target glyph coverage. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Select export fonts with required glyphs and verify embedding. Then open PDF on a device without development fonts. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
34. Warehouse addresses incorrectly reordered
What the reader experiences. Translated labels cause postal elements to appear in an unsupported sequence. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. Address data was built by concatenating translated fragments. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Use structured address components and locale-aware presentation. Then check real sample addresses from target territories. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
35. Build switches to fallback without notice
What the reader experiences. A release with missing translations silently offers a language as complete. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. Build checks only catalog existence and not critical-string coverage. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Gate release on essential message completion and disclose fallback. Then trigger safety and approval messages in advertised locales. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
36. Tooltips show obsolete workflow
What the reader experiences. After redesign the help text points to a removed toolbar icon. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. QML and translator catalogs were reviewed on different revisions. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Synchronize labels and examples with release source revision. Then follow the tooltip instruction on actual shipped UI. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
37. Qt Quick keyboard order not mirrored appropriately
What the reader experiences. RTL screens have an unexpectedly confusing focus sequence. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. Visual mirroring and navigation order were reviewed separately. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Test focus traversal with native RTL readers and adjust intentionally. Then finish transfer entry using keyboard only. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
38. Critical cancellation status softened
What the reader experiences. A translated cancellation appears like a reversible delay. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. The chosen term does not preserve process finality. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Review high-impact status language against state transitions. Then compare cancelled and postponed cases in context. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
39. Installer launches with inconsistent language
What the reader experiences. First-run wizard and main UI offer conflicting language choices. This is not adequately tested by seeing a line in a translator’s spreadsheet. Reproduce it as a real action performed by a person with a specific language choice, an actual user role and an application state that matters. Record which surface displays the problematic wording and what the reader is likely to conclude from it.
Where the meaning or delivery breaks. Installer and application use separate configuration stores. Investigate whether the failure belongs to string discovery, translation context, resource availability, runtime selection, user-interface layout or an underlying state transition. Keep these questions separate: a correct translation may be missing from a build, while an available translation may still describe the wrong outcome. Do not edit the business record just to make the wording look plausible.
Correction and evidence. Pass an explicit supported choice or explain the boundary. Then install from scratch with a nondefault UI language. Compare the result with both the source-language task and the authoritative state rather than relying only on a visually attractive screen. For release sign-off, note the tested locale, application version, action, expected result, actual result and whether a native reviewer understood the consequence without extra explanation.
A practical release checklist for the next multilingual build
Before extraction: inventory application-owned text, generated messages, native dialogs, printed reports, online help, audio, fonts and visual assets. Decide which source strings are command labels, which are status statements, and which are identifiers that must never change. Write translator notes for ambiguous terms and preserve a source revision so reviewers know exactly what they are translating.
Before packaging: validate every key and placeholder, distinguish required content from optional fallback, rebuild or reimport language resources and examine platform-specific output directories. Record the exact version of the toolchain and translation artifacts. Confirm that every offered language is present in the real installation or Player package, not merely in the repository.
During functional QA: start with a fresh user profile, make an actual record or game decision, deliberately create a failure, change language partway through the task and then reopen the saved state. Compare identifiers, numbers, approval or quest flags, dates, direction cues and document-language choices. Check visible messages and assistive text together, especially when an action is dangerous or irreversible.
During visual and linguistic QA: inspect the longest natural target strings, right-to-left mixed script, large accessibility text, narrow screens, keyboard navigation, native language phrasing, typography and required icon explanations. Ask reviewers what they believe happened and what they would do next; an accurate response is stronger evidence than their simply saying the sentence sounds fluent.
After publication: test an update from the previous version and keep a catalog of bug reports that includes the locale, build, resource or scene, reproduction steps and affected reader decision. Track correction as a product issue rather than a blame exercise for translators. Every change to a translated status should be checked against the actual state transition so a semantic fix does not create a new operational error.
Frequently asked questions
What is the difference between TS and QM?
TS is the translation source catalog. QM is the compiled runtime catalog. Update and review source messages before producing the distributable QM resources.
Do Qt Quick and C++ require separate translation systems?
They can share Qt’s underlying translation workflow, but source discovery, context, refresh behavior and packaging still need specific implementation.
Why does a QML label stay in the old language?
A binding or imperative assignment may not be re-evaluated when the translator changes. Test each existing view and use the Qt-version-appropriate refresh design.
Does lrelease translate unfinished messages?
Qt documentation describes how unfinished entries fall back to source text in the resulting catalog. Track coverage rather than equating a TS file with completion.
Should identifiers be translated?
No. Inventory, job and item identifiers should be preserved as data while their surrounding explanations are localized.
What makes a release ready?
An installed build must render the right messages during complete tasks, preserve stored records and pass accessibility, export and language-switch verification.
Official documentation and further reading
For verified implementation details consult Qt 6 internationalization, Qt 6 localizing applications, Qt Linguist lupdate, Qt Linguist lrelease. Documentation interfaces and version-specific APIs can change, so confirm guidance against the precise release in your project. For the wider translation system see Master Art of Translation: The Complete System. Explore other platform implementation chapters at the Translate Like a Pro series index.
Final principle: a successful language switch must preserve the user’s task
The strongest localization is neither the most literal nor the most elaborate. It is the one that makes a complete task understandable without changing the record, rule, permission, timing or outcome behind it. When people see a warning, they should understand the action it requires; when they see completion, it should correspond to a real completion event. That is how multilingual software becomes dependable rather than merely multilingual.