Qt Linguist Translation Guide | TS, Plurals and QM Files

Qt Linguist translation works best when you treat a Qt TS file as a structured record of what an application needs to say, not as a collection of English phrases waiting for substitutions. The quickest safe process is to update the TS files from the current application source with lupdate, translate with full context, preserve the correct placeholders and plural forms, validate the result, generate QM files with lrelease, and test the real application under the target language. A sentence is finished only when it is both natural and correctly delivered.

If you are searching for how to translate Qt TS files, how Qt Linguist handles plurals, or how to fix missing Qt translations, start by distinguishing the formats. In this context, TS means Qt’s XML translation source format, not TypeScript. The translator edits TS resources, while a localized application commonly uses compiled QM translation files. A perfectly good translation left in the TS file may never reach users if the right QM file is not built, deployed or loaded.

This guide explains the complete Qt translation path: source extraction from C++ or QML, contexts and disambiguation, translation statuses, numbered arguments such as %1, quantity forms, ampersand mnemonics, shortcuts, rich text, XML integrity, stale and obsolete entries, lupdate, lrelease, validation tools, language switching, locale formatting and runtime testing. Each step protects a different reason a translation might look correct in an editor but fail in the application.

How the Qt localization pipeline fits together

Qt applications can mark translatable text in C++, QML and UI files. The lupdate utility scans the configured inputs and creates or updates TS catalogs. Translators use Qt Linguist or another compatible tool to enter the target wording. The lrelease utility converts the reviewed TS content into the compact QM files that a deployed application can load through its translation infrastructure.

Think of this as five linked checkpoints: original code, translation-source catalog, target-language decisions, compiled resource, and visible user interface. Errors can enter at any checkpoint. If a phrase never appears in a TS file, the extractor may have missed it. If the target translation is absent from QM output, the message state or release configuration may be responsible. If QM exists but the UI stays in English, language loading or fallback may be at fault.

Before undertaking a new batch, trace one simple menu label from the source to its TS entry and then to the running app. Record the Qt version, localization build command, translation directory and how QTranslator is installed or how the application’s equivalent runtime integration works. Those facts make every later problem easier to diagnose.

TS is an XML catalog with a translation contract

A Qt TS file has structured XML containing contexts and messages, source strings, translated strings and sometimes comments, location data and numerus information. The source phrase is part of how some lookup paths identify a message, together with its context and any relevant disambiguation. The translation field supplies target-language wording. ID-based Qt translation is also supported, so the exact lookup contract must be identified for the project.

Do not let a generic file translator change XML tag names, context identifiers or message identity fields as though they were prose. The final text may read beautifully, but an app requesting the source message from a particular context will not find an entry that has been moved or incorrectly rewritten. Likewise, changing a source value inside the target catalog is not the same as translating the target value.

Use a TS-aware editor or a safe import/export filter. Preserve the structural information that connects the translation to application code. When reviewing raw XML, remember that the visible text is represented through XML escaping rules, which are distinct from Qt’s runtime argument replacement and mnemonic handling.

Context tells you what an English word means

Qt contexts often group messages by the class, QML component or other source location that requests them. An English word such as Open can mean open a file, open a connection or describe a document state. Translating it the same way everywhere because the source letters match can produce an interface that sounds wrong or gives the user the wrong expectation.

Qt Linguist provides context views to help translators choose wording. Ask for screenshots and the purpose of the control as well. A menu item that opens a document may need a verb form, while an item in a status column may need an adjective. A phrase that is grammatically correct in one dialog can be incorrect in another.

Build a terminology register that distinguishes concepts rather than insisting on one universal equivalent for every source word. Record whether a phrase names an object, labels a choice, describes a status or commands an action. This allows safe reuse while avoiding the common trap of translating isolated labels without knowing what they do.

Use disambiguation comments when the context is still not enough

Two messages can share the same English text and even appear in the same context while meaning different things. Qt provides ways for developers to supply disambiguation comments, and Qt Linguist can display relevant developer notes. When an entry has a note identifying the recipient name rather than a sender name, a language with different grammatical requirements can choose the correct form.

Do not ask a translator to invent context from the key or from the source phrase alone. Send ambiguous items back to the developer with a clear question. Is Charge a payment request or a battery status? Does Close dismiss a dialog or terminate an account? Can the command be undone? These are product facts that determine translation choices.

Keep the clarifications attached to the message as the source evolves. A comment may outlive a UI change and become misleading if no one updates it. Version-control the explanation with the source contract and include it in the translation handoff, so the next reviewer does not solve the same ambiguity from scratch.

Extract source messages with the actual project configuration

The lupdate tool finds source text marked for translation in configured application inputs. Qt supports workflows covering C++, QML and relevant UI resources. A translation catalog produced from an incomplete list of source files cannot include messages the extractor never sees. A contributor may believe the target locale is finished while a newly added dialog remains entirely in the source language.

Check the build system’s translation targets and source definitions. In modern Qt CMake projects, Qt-provided translation commands can coordinate lupdate and lrelease. Older projects may use different qmake-related workflows. Follow the actual project rather than copying a one-line command from an unrelated example that scans only one file.

Confirm a predictable extraction result. Add a harmless test message in a development branch, run the project’s update target, and verify that it enters the intended TS catalogs with useful context. Remove the test afterward. This gives translators confidence that they are working with a complete and current view of the product rather than an old snapshot.

lupdate should preserve existing translations while finding changes

Qt’s update workflow can merge current source messages into existing TS catalogs and retain translations for unchanged content. It can also identify messages that are new, changed, vanished or obsolete according to the project’s update process and options. These states matter because an old target sentence may no longer match the current source intent even when its wording looks close.

After lupdate runs, review the diff. Which contexts changed? Which source texts were edited? Did comments or numerus requirements change? Did a message move to a different class? A massive unexplained catalog change can signal that the tool scanned a different source set, altered source locations or applied unfamiliar options.

Do not bulk-mark all old translations as finished after a merge. A message that used to say Delete draft may now say Delete all drafts. The extra word changes the consequence. Give linguists a change report that identifies new and semantically changed entries so they can focus on work requiring renewed attention.

Translation state is not merely an editor decoration

Qt TS entries can carry status information such as unfinished translations. That status affects release behavior and what gets included or substituted. Qt’s documentation explains how lrelease handles completed versus incomplete translations and offers options for release checks. A target sentence pasted into a field is not necessarily available to users if the message has not been accepted as finished.

Establish a review rule. A translator may propose a target, but a designated reviewer confirms accuracy and context. Structural validators may flag placeholders, mnemonics and punctuation. Only after required checks pass should the entry be marked in the state expected by the release process. The precise status policy depends on the application and lrelease options.

Do not equate finished status with perfect quality. It is a workflow state, not a linguistic proof. The app still needs runtime tests. Conversely, an unfinished entry may contain a valid draft that should not be silently deployed. Make those decisions visible instead of relying on the accidental defaults of an export tool.

Why QM output must be inspected

The QM file is the runtime-oriented binary artifact produced from TS input. If the generated output is missing, outdated or never loaded, the application may display source text even when translators have approved every target entry in the TS file. This makes checking the compiled artifact a mandatory release step.

Run lrelease with the project’s intended options and inspect its warnings or failure status. Confirm that the generated QM is placed where packaging expects it. Then start the application in the target locale and request a distinctive message. If English remains, trace resource loading before making further changes to the translated sentence.

Some release workflows omit unfinished entries or treat them differently from completed ones. Test the actual flags rather than assuming all text present in TS will appear. A simple smoke test that checks a known translated phrase can expose a missing release step before the problem spreads across an entire application.

Preserve Qt numbered arguments such as %1 and %2

Qt strings frequently include numbered placeholders that are replaced at runtime. A source sentence might say Processing %1 before %2. In a target language, the phrases may need to appear in reverse order. Qt’s numbered arguments make this possible because the replacement identity is carried by the placeholder number rather than by its position in the sentence.

Do not translate %1 into a new token or replace it with a literal sample filename. The target must retain the data the application actually supplies. A checker should compare the relevant placeholder inventory while allowing reordering. Counting percent signs is not enough to detect a swapped or missing identity.

Ask developers what each placeholder represents. Two file paths, a path and a duration, or an amount and a percentage may require very different grammatical treatment. Test with values that cannot be confused, such as an obviously long filename and a small numeric duration. That catches accidental argument swaps much more quickly than tests using two similar short numbers.

Distinguish Qt placeholders from printf and other formats

Not every percent sequence in software is equivalent. Qt translation placeholders such as %1 and Qt’s quantity-handling syntax have their own contracts. A project may also use standard C++ formatting, QString formatting or third-party tools in other parts of the codebase. The extractor and the consuming call determine which rules apply to each message.

Create a format inventory for the message before editing. Does the application substitute QString::arg values? Is a quantity passed for a numerus translation? Is a literal percent sign displayed as part of a percentage label? Do not normalize all placeholders into a single style because the source happens to contain a percent character.

Technical QA should check the actual formatter. A generic regex may accept a target that later displays %1 literally or reject an intentional percent character in ordinary prose. Distinguish data tokens, numeric formatting and punctuation, and give linguists a rendered example instead of relying only on raw syntax.

Translate plural messages using the target language’s rules

Qt can mark messages for plural handling, with language-specific forms shown for translation. In many Qt applications a quantity is passed to a translation call and the translated message uses %n where the number should appear. The resource then needs the correct forms for the target language rather than a mechanical duplicate of English singular and plural.

Qt Linguist adapts the number of plural-form fields to the target language. This is important because English’s usual one-versus-other distinction does not cover languages with more categories. A translator should provide natural text for each required form, keeping the intended object, action and any inserted values correct. The number itself should remain data supplied by the application.

Test the selection under real target locales. Include zero, one, two, three, five, eleven and other values relevant to the language. The question is whether the correct message appears for the real quantity, not whether a reviewer can label each branch by intuition. Different languages can select different forms for the same number.

Review plural wording as a complete user message

A plural translation is not just an inflected noun. The verb, adjective, pronoun or whole sentence may change with quantity and grammatical context. Some languages also handle zero as an empty state with a different natural construction. When the UI communicates that a user is about to delete several files, the target must retain the consequence and object across all forms.

Provide context about the operation. Are files selected, processed, removed or recovered? Is the count exact or approximate? Does a value describe an elapsed duration, a stock quantity or the number of people involved? Translators can then choose grammar that works for every branch without changing the meaning of the operation.

Test boundary and unusual values. A negative quantity may not be meaningful for a count of selected items, but could appear in a temperature or account balance context. Do not invent a plural rule to handle bad data; clarify whether the caller should constrain inputs. Localization can make valid data readable, but it should not hide application logic defects.

Ampersand mnemonics are functional shortcuts

In Qt menu labels, an ampersand can mark a mnemonic character, often shown as an underlined letter used with Alt. An English File menu might assign F, while the corresponding target-language word may not contain that letter. Translators should choose a suitable character and ensure it does not conflict with nearby menu items in the relevant context.

An ordinary ampersand intended to appear as punctuation is a different case. Do not remove or insert ampersands casually. A target sentence about research and development should not accidentally create a keyboard accelerator, while a translated menu item should not lose a required mnemonic without a deliberate decision. The meaning of the symbol depends on the UI layer.

Qt Linguist includes accelerator-related validation that can help catch mismatches. Use it as a prompt for review, not as a substitute for testing the menu. A technically present mnemonic can still collide with another translated option or be attached to a character users cannot easily reach. Run the actual keyboard interaction in the target interface.

Translate keyboard shortcuts with a product-wide view

Some keyboard shortcuts appear as translatable strings, separate from the menu item they activate. A shortcut such as Ctrl+N may be familiar, but another key may be more suitable or already reserved in a target language or operating system. Changing it in one string without checking the application’s other commands can produce conflicts.

Qt’s translator guidance specifically warns against translating the Alt, Ctrl or Shift words arbitrarily, because the framework recognizes these components and can localize how they are presented. A translator may need to adjust the letter or digit in an approved shortcut, but that is a usability decision with technical consequences. Always test the resulting action.

Maintain a shortcut map for each supported locale, including system-reserved combinations. When a conflict is found, coordinate with the UI owner and review the whole menu set. A natural translated command label is not enough if the shortcut activates the wrong action or becomes impossible to use.

XML structure and entity references must survive export

TS resources are XML files. A generic translator or export script can break them by turning a markup entity into raw syntax, removing quotation marks from an attribute or rewriting a message element. Even if the translated text looks good, malformed XML can prevent lrelease or other tooling from processing the file.

Use a parser-aware workflow. Protect context and message structure and expose only translatable text content. Run a no-change round trip before a large job: import a representative TS file, export it without translating, parse it and compare message identity, plural structure and placeholders. A filter that fails this test is not ready for production.

When translating documentation displayed inside the app, a literal less-than sign or ampersand may be important. Correctly escape it for XML while preserving the intended displayed character. Do not delete punctuation merely to satisfy the serializer. Representation errors and linguistic errors should be diagnosed separately.

Rich text in Qt messages requires special care

Some Qt labels display text with formatting, links or markup-like content. A translator may need to move emphasized words or a clickable phrase to fit target grammar. If the application assumes a fixed English word position, the target can display the wrong link or apply styling to an unrelated phrase. That is an implementation limitation, not a reason to write unnatural language.

Identify how the particular component interprets text. Is it plain text, rich text or a supported markup subset? Does the widget escape user-provided values appropriately? A translation file should not be used to introduce arbitrary executable markup. The host application remains responsible for safe rendering and permitted interactions.

Test the resulting UI. Click links, use keyboard focus, inspect emphasis and listen to accessible text. A visually correct sentence with a broken hyperlink is an incomplete translation. Keep semantic markup and runtime behavior as part of the message’s contract rather than treating formatting as an afterthought.

Use Qt’s locale formatting instead of hard-coded English conventions

Dates, times, decimal separators, digit shaping and measurement conventions can differ across locales. A translation of words around a number is not the same as localizing the number. Qt offers locale-aware facilities such as QLocale, and applications should use them where appropriate rather than embedding English-formatted data in strings.

Review the data source and formatting call. A time shown as 10/11 could mean different dates under regional conventions. A decimal value with commas and periods swapped can cause a financial misunderstanding. A product code, on the other hand, often needs exact reproduction rather than localized punctuation. Specify which values are display data and which are identifiers.

Test assembled sentences with realistic values, not only source-language placeholders. The label, unit, date format, amount and punctuation should work as one piece of communication. If the app concatenates separate fragments into a sentence, consider an application improvement to allow natural target-language word order.

Test layout in C++ widgets and Qt Quick

A translated message may be longer than the English source. A fixed-width button can clip, a table heading may wrap unpredictably, or a warning dialog may become too tall for a small display. These are interface problems that cannot always be solved through shortening the target text. The product should preserve important meaning while adapting layout.

Test representative locales across different screen sizes and font settings. Consider German text expansion, CJK line breaks, Arabic and Hebrew directionality, and accessibility scaling. Qt applications can combine widgets, Qt Quick components and custom rendering, each with distinct layout considerations. Use the actual component rather than a generic text preview.

When a line must be shortened, define the essential information and approve an idiomatic shorter version. Do not remove a warning consequence or privacy condition to make a label fit. A responsive layout change is often better than a linguistically misleading shortcut.

Right-to-left text needs runtime inspection

Arabic and Hebrew translations can mix right-to-left prose with left-to-right URLs, account codes, dates and product names. These combinations affect punctuation placement, text selection and visual order. The stored string may be logically correct while the rendered UI makes it difficult to read or copy.

Test with real data under the target locale. Include a Latin email address inside Arabic text, a long numeric identifier, a path containing punctuation and an English product name. Check both the visible order and the copied text. Also test control placement and icon direction where the UI design expects mirroring.

Avoid invisible-direction-character patches inserted across resource files without diagnosing the renderer. Some cases need proper directional isolation or layout support in code. Linguists should approve the reading order and grammar; engineers should ensure the component displays mixed-direction data reliably.

Check accessibility and keyboard workflows

Qt applications include users who navigate by keyboard or rely on assistive technology. A short label can have a large functional consequence. If a translated menu item has the wrong accelerator or an accessible description is missing, users may be unable to discover or activate a feature even when the rest of the interface is readable.

Include tooltip text, status announcements, error descriptions, form labels and keyboard shortcuts in the translation inventory. Distinguish visible wording from accessible explanations rather than copying one phrase into every field. A user who cannot see an icon may need a specific action name, not a decorative description.

Perform a guided keyboard-only walkthrough. Can the user reach the menu, activate the intended command, understand a confirmation and recover from an error? Use screen-reader checks where the framework and platform expose accessible names. Language QA should verify that the complete task remains possible, not just that static text is grammatically correct.

Translation memory should preserve context and placeholders

Translation memory can speed repetitive interface text, but identical English text may not mean the same thing in every Qt context. The word Print might be a menu command or a property of a document. A fuzzy match from one context can yield a misleading target in another. Reuse should consider context name, developer comment, message function and placeholders.

When importing old translations, compare the current source meaning. A resource that once referred to one selected file may now refer to several. A new placeholder might represent a directory rather than a file. Treat those changes as translation updates, not opportunities to maximize match percentage without review.

Keep a termbase for stable product concepts and a record of approved exceptions. A translation that differs from an established term is not necessarily wrong if the context changes the grammar. The reviewer should know when consistency supports clarity and when mechanical sameness would sound unnatural.

Use Qt validation tools appropriately

Qt Linguist can check issues such as accelerator consistency, placeholder consistency and punctuation differences. Qt also provides command-line tools for validation in supported toolchain versions. The lcheck documentation describes checks for accelerators, surrounding whitespace, ending punctuation and place markers, with options for CI use. The exact availability and options should be verified against the installed Qt version.

Run the validators after importing translated TS files. Investigate every high-risk result. A missing %1 can be a release blocker because the UI loses data. A punctuation difference may be intentional in a language that uses different question marks, so it needs contextual judgment. Validator output should not force target punctuation to imitate English when that would be unnatural.

For the release compilation step, lrelease supports options that can report invalid or unfinished translations in modern Qt versions. Use the flags available in the current toolchain and make failures visible in the build logs. A check that developers never see does not meaningfully protect the release.

Keep stale, unfinished and obsolete content visible

When source code changes, catalogs may contain entries that are no longer used. Qt’s update tools can mark or manage these states depending on options. Removing all obsolete entries without a plan can destroy valuable historical translations or confuse teams supporting older branches. Keeping everything forever can make the catalog noisy and invite accidental reuse.

Classify entries deliberately. Which messages still exist in the current product? Which are retained for an older release? Which have been replaced by a new source text? Which await review? Provide translators with a changed-items report so they do not spend hours polishing wording that is no longer delivered.

At release time, ensure that unfinished and obsolete status does not silently become a false coverage number. A translation report should count messages that are actually used and delivered, not merely cells containing text in an editor. The deployed QM is the decisive artifact for runtime behavior.

Dynamic language switching may require refreshing the UI

Some applications allow users to change language without restarting. In that case, loading a different translator object may be only part of the work. Widgets and QML components may need to update their visible strings after the language changes. If the app continues to show old text in one panel, the target translation file may be correct while the UI has not refreshed.

Test a complete language switch after startup. Open a settings dialog, change the target language, visit previously opened windows and check menus, tooltips and notifications. Some controls may be created lazily and update while existing controls remain stale. Record the state and action that trigger the inconsistency.

Route this to application engineering rather than asking translators for alternate wording. A message cannot refresh itself merely by being present in TS. The fix belongs to the code that responds to a language change and updates the relevant views.

A worked problem: %1 and %2 are swapped

Imagine an alert that tells users which document will be processed after another. The source uses %1 for the current document and %2 for the next one. A target sentence legitimately reorders words but accidentally associates the second placeholder with the first document’s grammatical role. The output remains fluent yet gives the wrong processing sequence.

Reproduce the message with two unmistakable values, such as Report-A and Invoice-B. Compare the observed output with the intended sequence. Correct the placeholder positions without forcing English syntax onto the target sentence. Then run the same test in the application to verify the real caller supplies the documented values.

Add a placeholder contract to the translator note. A raw count of % signs would not explain their meanings. A short annotation and one test case prevent this class of confusion in every later update.

A worked problem: the translated menu loses its mnemonic

A menu label is translated naturally, but the ampersand marking its accelerator is removed. The UI looks correct to someone using a mouse, yet a keyboard user can no longer activate the command using the expected mnemonic. A validation warning might point to the missing ampersand, but a human must still decide which target-language character is appropriate.

Choose a reachable, memorable mnemonic that does not conflict with nearby menu entries. Update the translation, test the actual shortcut and confirm the menu still reads naturally. If the language lacks a convenient character, involve the UI owner rather than inventing an inaccessible combination.

This example shows why language decisions and interface behavior cannot be separated. The best target-language word must remain usable as a control. A build and a screenshot alone cannot demonstrate that.

A worked problem: a TS file changes but the QM does not

A translation reviewer approves a corrected warning and saves the TS file. A tester reports that the same old wording appears in the app. The target resource is correct, but the build may be using an older QM file. Check the compilation step, output directory, deployment package and runtime loading path.

Run lrelease through the project-defined target and verify that the expected QM artifact changes. Then launch a clean build in the target language and inspect the message. If the old wording remains, identify the actual translation resource loaded by the application. Do not edit the translation a second time without evidence.

A regression test can check one distinctive value from each target catalog after packaging. This small release smoke test prevents a whole batch of approved translations from being invisible to users.

An end-to-end quality gate for Qt translations

Begin with source extraction using the project’s configured lupdate workflow. Reconcile new and changed entries, attach developer context and protect message identities. Translate with a TS-aware tool. Check plural variants, placeholder identities, mnemonics, shortcuts and markup. Run XML parsing, Qt Linguist checks and the command-line validators available in your version.

Next compile with lrelease and inspect unfinished or invalid entries. Package the right QM files and verify that the app loads them for the expected locale. Run a small screen matrix that includes ordinary labels, plural counts, variable substitution, keyboard navigation, an error message and language switching if supported.

Finish with target-language review. Is the message accurate, comprehensible and natural? Does the reader know what action to take? Can every essential control be used with a keyboard or assistive technology? A full pass means both technical delivery and human usability, not simply a green compile icon.

Frequently asked questions about Qt Linguist

Is a Qt TS file a TypeScript source file? No. Qt’s TS file is a translation-source XML catalog. It is edited through Qt Linguist or compatible localization tools and can be compiled into a QM translation resource.

Why are my Qt translations not appearing? Check whether the correct TS entries are marked ready, whether lrelease produced an up-to-date QM file, whether that file is deployed, and whether the application loads the intended translator and locale.

Can translators change the order of %1 and %2? Yes. Numbered placeholders can be moved to match target-language word order while preserving which runtime argument each represents. Test with distinct sample values.

Does every language use two plural forms? No. Qt Linguist provides forms according to the target-language plural rules. Test multiple real quantities through the application’s translation APIs.

Should I translate Ctrl or Alt in keyboard shortcut strings? Qt’s guidance says not to translate those modifier names arbitrarily because the framework recognizes them. Shortcut letters may be reviewed in context, including conflicts.

Is a valid TS file enough for publication? No. The required target translations must be compiled, deployed, loaded and read in context, with meaningful and usable wording.

Official Qt references and a practical starting point

Qt’s documentation explains the complete translation workflow: https://doc.qt.io/qt-6/qtlinguist-index.html . For the TS to QM release process see https://doc.qt.io/qt-6/linguist-creating-ts-files.html and https://doc.qt.io/qt-6/linguist-lrelease.html . Translation-specific instructions are at https://doc.qt.io/qt-6/linguist-translating-strings.html and the toolchain’s validation reference at https://doc.qt.io/qt-6/linguist-lcheck.html . Check these against the Qt version installed in your project.

Choose five representative messages from an actual Qt application: a simple label, a sentence containing %1 and %2, a numerus message, a menu mnemonic and a message with developer context. Run lupdate, translate them, validate, compile with lrelease, load the resulting QM and use each message in the target-language interface. Once that small end-to-end test works, the same disciplined pipeline can protect the entire translation catalog while language specialists focus on clear, trustworthy communication.

How People Translate Quickly | Qt Linguist TS File QA: Context, Plurals, Placeholders, Mnemonics and QM Releases