Internationalization: Translating the OpenStudioApplication to another target language
We are now only translating the first tab (Location: Site, Design Days) and the WaitDialog (the messages you see when you open the OSApp).
This is a proof of concept, and we're hoping to extend it later to the full OpenStudio Application. The proof of concept hopes to achieve two things:
- Test the process of having external contributors do the translation, including some with little coding experience
- Drive interest in supporting the full development of the feature (via in-kind or financial contributions):
- Translating is somewhat easy ("just" need someone who knows English and the target language) and relatively fast, the problem is setting up the app so you can translate it and that takes some annoying code changes.
| Language | Locale code | Contact | 1st tab translated |
|---|---|---|---|
| English | en | default | X |
| French | fr | Julien Marrec | X |
| Spanish | es | Luis Lara | X |
| Chinese | zh_CN | Mingbo Peng | X |
| Greek | el | Alex Vlachokostas | X |
| Polish | pl | Bartłomiej Tokarzewski | X |
| Catalan | ca | Adrià González | X |
| Farsi-Persian | fa | Maedeh Mohit | X |
| Hindi | hi | Gurneet Singh | X |
| Japanese | ja | Ken Takahashi | X |
| Italian | it | Carmine Andrea Rago | X |
| German | de | Philipp Bruggmann | X |
| Vietnamese | vi | ThanhVu Tran | X |
| Hebrew | he | Michael Levy | X |
Qt uses TS files which is a special kind of XML format, which will map the strings wrapped in tr("string") in your source code to the appropriate locale (the creation and update of the TS is automatically done to match source code, but a manual step of actually translating is required). That gets compiled into a special file format (QM) that is available to the executable at runtime, and I added menus to load them.
Qt provides a tool to ease the translation called Qt Linguist that must be used. Two options are available to you:
- If you plan on actually build the OpenStudioApplication to test your changes or contribute it another way: make a full install of Qt 5.15.0. It is provided when you install Qt 5.15.0 (Open Source Qt: https://www.qt.io/download-qt-installer, see how to with screenshots on Configuring OpenStudio Application Build Environment. Note: that takes several GB to install.
- If you are not planning to actually build the OpenStudioApplication, you should try out these standalone installers available for windows and mac (no linux) that only take several MB: https://github.com/lelegard/qtlinguist-installers/releases/tag/v5.12.0.
Qt Linguist looks like this, here I have loaded the OpenStudioApp_es.ts for Spanish.
Note: I launched Qt Linguist from a checkout of the github repo, on the branch Internationalization (TS files are in the translations/ subfolder), so I see something in "Sources and Forms". This is optional, but provides context for the strings you are translating.
As you can see the "Source text" is Date, so in the box Translation to español de España I will type Fecha and validate with CTRL+ENTER. The Checkbox turns green and it moves to the next field...
If it turns Yellow (or is marked red before you validate), you will find an explanation in the bottom "Warnings" pane, usually it's something about not having the same leading and trailing whitespaces as the source text. Note that you also need to match newlines, which you can add by hitting ENTER.
Do the same for all fields. Then Save the file, and send it back to me (or commit to a branch on a fork of OpenStudioApplication repo if you're comfortable with that)
Add a new entry in translations/CMakeLists.txt for a new TS file by naming it with the target locale (eg: fr for French, el for Greek, etc). Then rebuild the project via the specific target: make update_translations. A new TS file will be generated for you in <root>/translations/.
You will also want to edit src/openstudio_lib/MainMenu.hpp and src/openstudio_lib/MainMenu.cpp to connect some buttons to load the target language.
An example of such a commit can be found in https://github.com/openstudiocoalition/OpenStudioApplication/commit/f7ee282a3c85fa09dc11dfadcdbc115e06281829