Skip to content

Latest commit

 

History

History
62 lines (48 loc) · 3.82 KB

I18N.md

File metadata and controls

62 lines (48 loc) · 3.82 KB

How to translate?

Glad you asked! This tool is using a rather old-fashioned approach using the gettext tool suite. Let's quickly dive into the process how you create a translation for the tool!

!!! Please be aware that currently Translating only really works nice on Linux (and Mac most likely ... if you have bash in place, that is), due to the custom scripts provided to help with the process. I hope that I will find some time to provide a solution for Windows, one day. Feel free to send a pull request, if you worked something out before I was able to fix this !!!

About adding new classes

You can skip this step if you just want to translate the tool in its current state!

However, if you add a class to the tool and want to have it translated, you would usually first of all by pasting those lines into the new class file:

# Set the local directory
localedir = "./locale"

# Set up your magic function
translate = gettext.translation("**PYTHONCLASSFILENAME**", localedir, fallback=True)
_ = translate.gettext

Make sure to replace **PYTHONCLASSFILENAME** with whatever the name of the new class might be, e.g. MainWindow. Now, whenever you want to output a String to the user make sure to insert it like this into the source code of the class: _("Translate me"). The part inside the brackets is actually called the Message ID. For Easy MQTT Handler the decision was made that the Message ID should always match the English version of the particular text that should be shown inside the GUI. The reason for this decision is that it makes the translation process a little bit more convenient, as translators will always have the English version present for reference. Besides that using this approach it can be ensured that the tool will always at least present an English interface, even if the language files have been forgotten to be released or deleted by the user.

Once you placed the new placeholders in the source code, you can move on to compiling a template for the translation process.

Compiling templates for translation

First you need to create template files (*.pot). Got you covered here, just execute make translation-templates in the repos main directory.

Creating the translation

Now that you have the template files (*.pot), which you can find in ./src/easy_mqtt_handler/locale/templates/, you can just open them with a text editor of your choice and start translating.

  1. Once you are done with the translation rename the *.pot files to *.po
  2. Next put the new language files into ./src/easy_mqtt_handler/locale/**LANG**/LC_MESSAGES/ (make sure to replace **LANG**with an appropriate ISO Code, check: https://en.wikipedia.org/wiki/ISO_639-1).
  3. Now you need to compile to *.po files to *.mo files. Again we've got you covered, just execute make compile-translations in the repos main directory.

Testing translations

Now you are ready to test your translation. To test an arbitrary new language you can start the tool like: LANGUAGE=LANGISOCODE python3 ./__main__.py (run this inside src/easy_mqtt_handler!). If you've done everything correctly you should be able to see the tool starting using the new language. Honestly, I cannot really tell how this would work with right-to-left (RTL) languages, e.g. Persian, Arabic or Urdu, as I speak and write neither of those, but if you really want to translate into an RTL language, please do not hesitate to reach out and ask for assistance should you face any problems.

Contributing your translation

If you want to contribute your translation back to this project, please open a pull request which adds your ./src/esay_mqtt_handler/locale/LANG/ directory to the project's repo. Once we've merged it your contributed language will be available for everyone!

Thanks for considering to support this project with your contributions!