Qt Localization: Difference between revisions

From Qt Wiki
Jump to navigation Jump to search
(instructions regarding branches)
Line 1: Line 1:
[[Category:Developing_Qt::Guidelines]]
[[Category:Developing_Qt::Guidelines]]


== Translating Qt Into Other Languages ==
==Translating Qt Into Other Languages==


Qt aims at being fully internationalized by use of its own [https://doc.qt.io/qt-5/internationalization.html i18n framework].
Qt aims at being fully internationalized by use of its own [https://doc.qt.io/qt-5/internationalization.html i18n framework].
Line 25: Line 25:
The Qt Project has [https://www.transifex.com/qtproject/public/ a presence on Transifex], but this does not affect the submission process itself.
The Qt Project has [https://www.transifex.com/qtproject/public/ a presence on Transifex], but this does not affect the submission process itself.


=== Instructions for Qt ===
===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 ====
====Updating existing translations for a new minor release====


===== Qt 6 =====
=====Qt 6=====


* [[Building_Qt_6_from_Git|Build Qt]]
*[[Building_Qt_6_from_Git|Build Qt]]
* Parse the code for new translated messages by running <code>cd qttranslations ; <qt-installation>/bin/qt-cmake . -G Ninja; ninja ts-<lang></code>
*Parse the code for new translated messages by running <code>cd qttranslations; <qt-installation>/bin/qt-cmake . -G Ninja; ninja ts-<lang></code>
* You should see the .ts files for the language being modified  
*You should see the .ts files for the language being modified
* Translate missing/new messages using Qt Linguist
*Translate missing/new messages using Qt Linguist
* Create a commit by running <code>ninja stage-ts</code>
*Create a commit by running <code>ninja stage-ts</code>
* Push the commit to gerrit for review
*Push the commit to gerrit for review


===== Qt 5 =====
=====Qt 5=====


* [[Building_Qt_5_from_Git|Build Qt]]
*[[Building_Qt_5_from_Git|Build Qt]]
* Parse the code for new translated messages by running <code>cd qttranslations ; qmake ; make ts-<lang></code>
*Parse the code for new translated messages by running <code>cd qttranslations; qmake; make ts-<lang></code>
* You should see the .ts files for the language being modified  
*You should see the .ts files for the language being modified
* Translate missing/new messages using Qt Linguist
*Translate missing/new messages using Qt Linguist
* Create a commit by running <code>make commit-ts</code>
*Create a commit by running <code>make commit-ts</code>
* Push the commit to gerrit for review
*Push the commit to gerrit for review (for the <code>5.15-tr</code> branch)


==== Starting a not-yet existing translation   ====
====Starting a not-yet existing translation====


The translation files live in a dedicated repository, [https://code.qt.io/cgit/qt/qttranslations.git/ qttranslations].
The translation files live in a dedicated repository, [https://code.qt.io/cgit/qt/qttranslations.git/ qttranslations].
Line 54: Line 55:
There are several ways to get them:
There are several ways to get them:


* You may [https://l10n-files.qt.io/l10n-files/ 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. <br />If there are no existing translations for your language at all yet:
*You may [https://l10n-files.qt.io/l10n-files/ 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. <br />If there are no existing translations for your language at all yet:
** To obtain the templates, you have two options:
**To obtain the templates, you have two options:
*** Start entirely from scratch by downloading the files labeled "templates" and renaming them.
***Start entirely from scratch by downloading the files labeled "templates" and renaming them.
*** Copy a translation for a language which is similar to yours.
***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).
**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.
**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 [https://codereview.qt-project.org/#/c/247698/ this tool] (it was not merged into the repository yet).
**To update partially done translations with the latest templates, you can use [https://codereview.qt-project.org/#/c/247698/ this tool] (it was not merged into the repository yet).
* Alternatively, if you are tech-savvy enough, you may build the files yourself:
*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:
**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 <tt>$PATH</tt> starts with <tt>$qt5/qtbase/bin</tt>
***Make sure your <tt>$PATH</tt> starts with <tt>$qt5/qtbase/bin</tt>
*** Change to <tt>$qt5/qttranslations/translations</tt>
***Change to <tt>$qt5/qttranslations/translations</tt>
*** Run <code>perl split-qt-ts.pl <lang></code>
***Run <code>perl split-qt-ts.pl <lang></code>
** Otherwise, to update the templates:
**Otherwise, to update the templates:
*** Run <code>make ts-<lang></code> in the <tt>$qt5/qttranslations/translations</tt> subdirectory, where <tt><lang></tt> is the language (and optionally country) code.
***Run <code>make ts-<lang></code> in the <tt>$qt5/qttranslations/translations</tt> subdirectory, where <tt><lang></tt> is the language (and optionally country) code.
*** You may also use <code>make ts-<part>-<lang></code> to update only a specific file.
***You may also use <code>make ts-<part>-<lang></code> to update only a specific file.
*** If a particular file (or all of them) for your language is missing, run <code>make ts-<part>-untranslated</code> (or <code>make ts-untranslated</code> 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 <code>make qmake</code> to cause the files being found by the build system.
***If a particular file (or all of them) for your language is missing, run <code>make ts-<part>-untranslated</code> (or <code>make ts-untranslated</code> 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 <code>make qmake</code> 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 <tt>qmake</tt> in the respective directory before running <tt>make</tt>. '''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.
**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 <tt>qmake</tt> in the respective directory before running <tt>make</tt>. '''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 …
**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 next step is doing the actual translation. :-)
Line 103: Line 104:
Finally, you need to [[Qt Contribution Guidelines|post a change on Gerrit]] for review.
Finally, you need to [[Qt Contribution Guidelines|post a change on Gerrit]] for review.


=== Instructions for the Installer Framework ===
===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 <tt>src/sdk/translations</tt> inside the [https://code.qt.io/cgit/installer-framework/installer-framework.git/ Installer Framework repository] itself. Note that the translations are compiled into the framework itself (run make in <tt>src/sdk</tt>), so it's somewhat hard to test them "in-vivo".
The instructions are almost identical to the ones for Qt, except that the translations and various ts- targets live in <tt>src/sdk/translations</tt> inside the [https://code.qt.io/cgit/installer-framework/installer-framework.git/ Installer Framework repository] itself. Note that the translations are compiled into the framework itself (run make in <tt>src/sdk</tt>), so it's somewhat hard to test them "in-vivo".


=== Instructions for Qt Creator ===
===Instructions for Qt Creator===


The instructions are almost identical to the ones for Qt, except that
The instructions are almost identical to the ones for Qt, except that
* the translations and various ts- targets live in <tt>share/qtcreator/translations</tt> inside the [https://code.qt.io/cgit/qt-creator/qt-creator.git/ Qt Creator repository] itself and
 
* new files need to be explicitly added to translations.pro.
*the translations and various ts- targets live in <tt>share/qtcreator/translations</tt> inside the [https://code.qt.io/cgit/qt-creator/qt-creator.git/ 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.
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.
Line 117: Line 119:
See also the [[Qt Creator Translation Page]].
See also the [[Qt Creator Translation Page]].


== Translating Qt Documentation Into Other Languages ==
==Translating Qt Documentation Into Other Languages==


The infrastructure for that is somewhat lacking. Still, there is for example the simplified Chinese doc translation.
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.
*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:
*Build your zh_CN documentation files:
** configure
**configure
** make
**make
** make docs
**make docs
** make docs_zh_CN
**make docs_zh_CN
** The viewable documentation files should appear in doc-build/html-qt_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.
*Remaining issue: no support for translating the in-source documentation of Qt classes.

Revision as of 09:30, 1 February 2023


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.