Qt is known for its good documentation, and in the recent years the number of users that rely on the documentation has grown considerably. Some of these users also prefer using the documentation in a specific language, so they use the auto-translation tools for the purpose. Most of these tools translate everything on a page to the chosen language, unless they are told not to. For example, the following screenshot shows the Google translate output of the QString API reference in French language:

Notice that the API summary for QString is also translated, changing the methods and properties'  name.

How do we tackle this problem?

The auto-translation tools can be informed to skip some parts of the documentation, especially the API reference summary. There are several ways to do this, and one of them is to use the translate attribute.

The QDoc tool that we use to generate the documentation, adds the "translate=no" attribute to the HTML blocks that should not be translated. This attribute enables the translation tools to skip those blocks when the user tries to translate a page, offering a better translation experience.

Is QDoc your documentation generator?

If you are using QDoc to generate documentation for your project, note that you can choose between HTML and DocBook XML as output format. Similar to the HTML output, QDoc generates DocBook XML with necessary metadata about non-translatable units. Typically, DocBook is used as an intermediate format, which can be processed further using another tool, such as pandoc.  These third party tools can use the metadata about non-translatable units to generate sensible HTML output.

In the following screenshot, you can see the how "translate=no" attribute affects the translation:

What's next?

The documentation sets on https://doc-snapshots.qt.io/ already use the translate attribute, and we will soon roll out the feature to the sets on https://doc.qt.io/. Try it out and let us know your experience. If you find any issues, do report it by creating a ticket on JIRA.