Qt Localization

Translating Qt Into Other Languages

Qt aims at being fully internationalized by use of its own i18n framework.

Localizations are provided on a best-effort basis by the community; the Qt Company employees involved in these activities are volunteering to do so. Here is how you can help:

Translation efforts are coordinated over the localization@qt-project.org mailing list. If you are starting an entirely new translation, please cross-post to interest@qt-project.org or qt-creator@qt-project.org respectively, to possibly find other interested people.

If you really do not wish to communicate in the open, you may contact oswald.buddenhagen@gmx.de. Real-time communication is possible in the #qt-labs and #qt-creator channels on irc.freenode.net. Ask ossi. (For a full list of IRC channels of interest to Qt developers, see OnlineCommunities.)

Please talk with us before you start - otherwise you may end up duplicating work, translating a dead or highly unstable branch, etc. We've seen it before.

You should probably check whether KDE already has a translation of Qt (v4.x) to your language and whether they would be willing (and legally able) to contribute it to Qt upstream. Even if not, somebody from the community may be willing to help you.

Preferentially, you should target the oldest still maintained LTS branch of Qt, and subsequently update the newer LTS branches and then the current stable or stabilizing branch.
Note that it makes little sense to start translating until a particular release cycle enters the string freeze, somewhere between the last beta and the first release candidate. Approximate release dates will be announced on the mailing list, usually leaving around two weeks for completing the translation. When you are starting somewhere in the middle of a release cycle, the only sensible option is translating the latest stable release.

The actual act of submitting a translation is the same as for source code (see Qt Contribution Guidelines).
In case you really cannot find your way through git/Gerrit and cannot find someone to help you, you may simply attach the ts files to an appropriate JIRA task (the respective components of the various products are named "Translations (l10n)"). Note that this process is suboptimal and may result in delays.
Do not create Github pull requests or send emails with attachments - we cannot process these for legal reasons.

The Qt Project has a presence on Transifex, but this does not affect the submission process itself.

Instructions for Qt

Note that unlike the rest of Qt, the translations still use a forward-merging branch model, so you should target the oldest branch you find still relevant first.

Updating existing translations for a new minor release

Qt 6

• Build Qt
• Parse the code for new translated messages by running

  cd qttranslations; <qt-installation>/bin/qt-cmake . -G Ninja; ninja ts-<lang>
  

• You should see the .ts files for the language being modified
• Translate missing/new messages using Qt Linguist
• Create a commit by running

  ninja stage-ts
  

• Push the commit to gerrit for review

Qt 5

• Build Qt
• Parse the code for new translated messages by running

  cd qttranslations; qmake; make ts-<lang>
  

• You should see the .ts files for the language being modified
• Translate missing/new messages using Qt Linguist
• Create a commit by running

  make commit-ts
  

• Push the commit to gerrit for review (for the

  5.15-tr
  

  branch)

Starting a not-yet existing translation

The translation files live in a dedicated repository, qttranslations.

First, you need translation templates to work with. Qt uses its own TS (translation source) XML file format for that. There are several ways to get them:

• You may download daily updated translation files. This page also lists the current release state of each branch, so you should visit it in either case. Note that many Qt 5 files show zero percent completion status - this is because the imported Qt 4 translations were all downgraded to "unfinished", not because the files are empty.
  If there are no existing translations for your language at all yet:
  • To obtain the templates, you have two options:
    • Start entirely from scratch by downloading the files labeled "templates" and renaming them.
    • Copy a translation for a language which is similar to yours.
  • Then adjust the language code inside the files (you can do that with Qt Linguist).
  • Do not qualify the language with a country unless it is reasonable to expect country-specific variants.
  • To update partially done translations with the latest templates, you can use this tool (it was not merged into the repository yet).
• Alternatively, if you are tech-savvy enough, you may build the files yourself:
  • If you are starting a translation of Qt 5 to a language for which a Qt 4 translation exists, you should re-use the existing translation files:
    • Make sure your $PATH starts with $qt5/qtbase/bin
    • Change to $qt5/qttranslations/translations
    • Run

      perl split-qt-ts.pl <lang>
      

  • Otherwise, to update the templates:
    • Run

      make ts-<lang>
      

      in the $qt5/qttranslations/translations subdirectory, where <lang> is the language (and optionally country) code.
    • You may also use

      make ts-<part>-<lang>
      

      to update only a specific file.
    • If a particular file (or all of them) for your language is missing, run

      make ts-<part>-untranslated
      

      (or

      make ts-untranslated
      

      to get all) and rename the file(s) accordingly. Do not qualify the language with a country unless it is reasonable to expect country-specific variants. Then run

      make qmake
      

      to cause the files being found by the build system.
  • Note that the above instructions assume that you have a configured and compiled Qt tree, in particular that Makefiles are present. If you want to use another Qt build (probably the one of your Linux distro), make sure you have qmake and the Qt Linguist tools installed, and run qmake in the respective directory before running make. Warning: This will not work if the installed tools are too old for the Qt sources, which happens from time to time when significant improvements to lupdate are made.
  • You can mix the two sources of templates, but you'll need to play with git to get what you want. It's really easier to just download the templates …

The next step is doing the actual translation. :-)

The "native" tool for translating TS files is Qt Linguist. It is pretty self-explanatory and comes with documentation.
If you prefer to use another tool (most probably because of better support for translation memory), you might need to convert the TS files to and from some other format:

 $ lconvert <file>.ts -o <file>.po
 $ <your-tool> <file>.po
 $ lconvert -locations none <file>.po -o <file>.ts

XLIFF might also work for your tool.

Note: Always use the latest stable Linguist tools available. Also, 3rd party tools like ts2po were known to cause trouble.

When you translate legal text like copyright notices or licenses, include a verbatim copy of the original below, and note that it is the authoritative version in case of doubt.

If you find that particular messages need additional context to be translatable, you should report that as bugs and ideally add //: comments to the code yourself if you can figure it out.

Don't hesitate to report mistakes in the original strings, though we can't merge these fixes during string freeze, obviously.

To test the translations live, just run make in the translations subdirectory and run whatever application that uses the strings in question. You will need to copy the QM file(s) to the installation directory of the Qt you are actually using if the Qt sources you are translating are not your current Qt installation.

It is essential that you mark finished translations as such - otherwise the script used for assessing the completeness will not see them and will exclude them from compilation in the release.

Next, if you are re-using a Qt 4 translation for Qt 5, run

lconvert -no-obsolete -i <file> -o <file>

to dispose of the old strings. Next, you need to commit any PRI/PRO files you modified and the TS file(s) you translated. If you added new files, first run

git add -N <files>

(the -N is important!). Then run

make commit-ts

to check in the files (you should have no other modified files due to the use of language-specific ts targets). The commit-ts target will also strip out line number information from the TS files to keep the changes smaller.

Finally, you need to post a change on Gerrit for review.

Instructions for the Installer Framework

The instructions are almost identical to the ones for Qt, except that the translations and various ts- targets live in src/sdk/translations inside the Installer Framework repository itself. Note that the translations are compiled into the framework itself (run make in src/sdk), so it's somewhat hard to test them "in-vivo".

Instructions for Qt Creator

The instructions are almost identical to the ones for Qt, except that

• the translations and various ts- targets live in share/qtcreator/translations inside the Qt Creator repository itself and
• new files need to be explicitly added to translations.pro.

Qt Creator will not use the translation unless it finds one for the Qt library as well. Qt Designer, Qt Assistant and the Qt Help library should be translated as well, though failure to do so will go unnoticed at first.

See also the Qt Creator Translation Page.

Translating Qt Documentation Into Other Languages

The infrastructure for that is somewhat lacking. Still, there is for example the simplified Chinese doc translation.

• English documentation is in doc/src. That structure can be mirrored into doc/src/zh_CN one to one, for all .qdoc files.

• Build your zh_CN documentation files:
  • configure
  • make
  • make docs
  • make docs_zh_CN
  • The viewable documentation files should appear in doc-build/html-qt_zh_CN.

• Remaining issue: no support for translating the in-source documentation of Qt classes.