Difference between revisions of "Qt Localization"

From Qt Wiki
Jump to: navigation, search
(fixed markup)
Line 7: Line 7:
 
Localization to languages for which The Qt Company has no internal resources needs to be provided by other parts of the community. Here is how you can help:
 
Localization to languages for which The Qt Company has no internal resources needs to be provided by other parts of the community. Here is how you can help:
  
Translation efforts are coordinated over the localization@qt.io mailing list. If you are starting an entirely new translation, please cross-post to interest@qt.io or qtcreator@qt.io respectively, to possibly find other interested people.
+
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@theqtcompany.com.
 
If you '''really''' do not wish to communicate in the open, you may contact oswald.buddenhagen@theqtcompany.com.
Line 18: Line 18:
 
Generally, 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.
 
Generally, 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]]).
+
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 contribute via email after accepting the CLA on Gerrit.
 
In case you '''really''' cannot find your way through git/Gerrit and cannot find someone to help you, you may contribute via email after accepting the CLA on Gerrit.
Line 27: Line 27:
 
There are several ways to get them:
 
There are several ways to get them:
  
* You may "download":ftp://ftp.qt.io/qt/l10n/index.html 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.
+
* You may "download":http://l10n-files.qt.io/l10n-files/ 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.
 
* 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 tranlation 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 tranlation files:
*** Make sure your <code>$PATH </code> starts with <code>$qt5/qtbase/bin </code>
+
*** Make sure your <tt>$PATH</tt> starts with <tt>$qt5/qtbase/bin</tt>
*** Change to <code>$qt5/qttranslations/translations </code>
+
*** 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 <code>$qt5/qttranslations/translations</code> subdirectory, where <code><lang></code> 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. You will also need to add the files to translations/translations.pro.
 
*** 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. You will also need to add the files to translations/translations.pro.
'''''' 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. :-)
 +
 
The "native" tool for translating TS files is Qt Linguist. It is pretty self-explanatory and comes with documentation.
 
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:
 
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:
Line 55: Line 56:
 
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.
 
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 <code>//:</code> comments to the code yourself if you can figure it out.
+
If you find that particular messages need additional context to be translatable, you should report that as bugs and ideally add <tt>//:</tt> 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.
 
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 <code>make</code> 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.
+
To test the translations live, just run <tt>make</tt> 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.
+
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 <code> lconvert -no-obsolete -i <file> -o <file></code> to dispose of the old strings.
+
Next, if you are re-using a Qt 4 translation for Qt 5, run <code>lconvert -no-obsolete -i <file> -o <file></code> 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 <code>git add -N <files></code> (the -N is important!). Then run <code>make commit-ts</code> 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.
 
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 <code>git add -N <files></code> (the -N is important!). Then run <code>make commit-ts</code> 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 [[Qt-Contribution-Guidelines | post a change on Gerrit]] for review.
+
Finally, you need to [[Qt Contribution Guidelines|post a change on Gerrit]] for review.
  
h3. Instructions for Qt Creator  
+
=== Instructions for Qt Creator ===
  
The instructions are identical to the ones for Qt, except that the translations and various ts- targets live in <code>share/qtcreator/translations</code>.
+
The instructions are identical to the ones for Qt, except that the translations and various ts- targets live in <tt>share/qtcreator/translations</tt>.
  
 
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.

Revision as of 10:42, 27 February 2015


Translating Qt Into Other Languages

Qt aims at being fully internationalized by use of its own "i18n framework":http://doc.qt.io/qt-5.0/qtdoc/internationalization.html.

Localization to languages for which The Qt Company has no internal resources needs to be provided by other parts of the community. 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@theqtcompany.com. Real-time communication is possible in the #qt-labs and #qt-creator channels on irc.freenode.net. Ask ossi|tt. (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":http://www.kde.org/ already has a translation of Qt 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":http://i18n.kde.org/teams-list.php may be willing to help you.

Generally, 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 contribute via email after accepting the CLA on Gerrit.

Instructions for Qt

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":http://l10n-files.qt.io/l10n-files/ 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.
  • 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 tranlation 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. You will also need to add the files to translations/translations.pro.
    • 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 relative <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 Qt Creator

The instructions are identical to the ones for Qt, except that the translations and various ts- targets live in share/qtcreator/translations.

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.

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: can't translate the in-source documentation of Qt classes. The infrastructure is in development; availability will be announced on the mailing list.