Skip to content

Translating OctoPrint

Gina Häußge edited this page May 3, 2017 · 21 revisions

Starting with version 1.2.0 OctoPrint is ready for being translated into various languages. In order to contribute a translation you have basically two options, online and locally via Github pull request. In any case please always make sure of the following points:

  • Keep whitespace like in the source, e.g. newlines
  • Keep/use HTML tags like in the source, e.g. <strong>...</strong>
  • Keep placeholders like %(...)d, %(...)s etc intact (just move them where they belong to in your target language, their names should hopefully be self explanatory -- if not please ask!)
  • Since OctoPrint is mostly targeted at the hobby segment of users, use the informal version of your language (if it distinguishes between formal and informal for "you" etc) for now. I'll keep looking into if it's somehow possible to distinguish between a formal and an informal version of the language, but until I find a way to do this, OctoPrint will pretend to be the buddy of it's users -- just think of how IKEA does it ;)
  • The application name "OctoPrint" is also a translatable string in order to allow you to migrate it into a different writing system (e.g. cyrillic, katakana...). Please make sure it stays recognizable nevertheless, e.g. leave it as is unless you absolutely have to adjust it to your writing system.

Translating

Translating online

OctoPrint uses Transifex for allowing easy translations via a web frontend. If you want to add a new or improve on an existing language within OctoPrint and don't yet have an account, please sign up for a Transifex account first. After that, navigate to OctoPrint's project page on Transifex. There you can either request the addition of a new language or -- by clicking on an existing one -- request to be added to that language's translation team. After your request has been accepted you'll be able to contribute translations :)

Translating locally

You can also contribute to OctoPrint's translations locally. You should be comfortable with editing gettext PO files for that, since this is what OctoPrint uses. There exist various editors for comfortably editing these files (e.g. Poedit), but you may also just use your preferred text editor.

The instructions on how to get everything up and running for that depend on whether you want to start translating based on an existing OctoPi setup or need to do a custom setup (e.g. on your desktop computer) first.

  • OctoPi: Log into your OctoPi installation via SSH and do the following

    sudo service octoprint stop
    source ~/oprint/bin/activate
    cd ~/OctoPrint
    python setup.py develop
    

    This will stop the server and make sure that all changes you do to your checkout folder (e.g. pulling in
    translations from Transifex or adding yourself through copying over the .po files) will become available without having to run python setup.py install everytime.

  • Custom: Start off by cloning OctoPrint and changing into the directory:

    git clone https://github.com/foosel/OctoPrint.git
    cd OctoPrint
    virtualenv venv
    source venv/bin/activate
    pip install -e .[develop]
    

The PO template file resides under translations/messages.pot, each language's PO file can be found under translations/<language code>/LC_MESSAGES/messages.po. Before starting on a translation you should always make sure that the PO template file is up to date and the PO files are updated accordingly, so always do a git pull first, then make sure the resources are really up to date. OctoPrint's setup.py script includes a couple of custom commands to help here. Using

python setup.py babel_refresh

you can perform a fresh extraction of all translatable strings from OctoPrint's source and update all PO files. From there you can edit your language's translation. If it's not yet available, you can create it via

python setup.py babel_new --locale=<locale>

You might want to check from time to time that everything looks fine. To do that, compile the translation into their MO and JS equivalents and "bundle" them with OctoPrint:

python setup.py babel_compile
python setup.py babel_bundle --locale=<locale>

Then startup OctoPrint (octoprint) and take a look at your translation results. To request a specific locale to display the UI in, you may append the query parameter l10n with the desired locale to OctoPrint's URL, e.g.

http://localhost:5000/?l10n=de

Alternatively you can select that locale in OctoPrint's "Appearance" settings or your user's Usersettings.

Transifex integration for local installations

You should take a look at the Transifex client which integrates wonderfully with a fresh OctoPrint git checkout. You can install it via pip:

pip install transifex-client

After that all tx commands should work (see tx --help or the online help for how to use it).

Retrieving translations

To pull the current translation of the locale you wish to translate, do

tx pull -l <locale>

Uploading translations

Edit your translation files either in your favourite text editor or with something like Poedit. Check if everything looks good. If yes, push your changes:

tx push -l <locale>

Checking your translation

If you have made changes to the translation files, you should check how everything looks. First get everything ready as you would for translating locally, like described above

Pull the translations you want to test, either by using the Transifex client (if you did the translation via its web interface) or by manually copying the po file to translations/<language code>/LC_MESSAGES/messages.po.

Then do the following:

python setup.py babel_compile
python setup.py babel_bundle --locale=<language code>

This will compile the translation files and copy them to the correct folder in OctoPrint so that they will become bundled on your copy and you don't have to continuously import language packs. You'll need to repeat these steps every time you change something in the .po file/pull from Transifex.

Restart the server (custom install: octoprint, OctoPi: sudo service octoprint restart). To request a specific locale to display the UI in, you may append the query parameter l10n with the desired locale to OctoPrint's URL, e.g.

http://localhost:5000/?l10n=de

You should also be able to select your locale under User Settings > Appearance and under Settings > Appearance. Note that it will NOT show up under the list of installed language packs -- you didn't install it as a language pack, you bundled it with your local OctoPrint installation.

Creating a language pack

If you are satisfied with your translation result, you can create a language pack. To do that, please run the following command (make sure to use the correct python version, so activate any virtual envs, e.g. source ~/oprint/bin/activate on OctoPi, or use the full path to python, e.g. ~/oprint/bin/python on OctoPi):

python setup.py babel_pack --locale=<locale>

This will create a ZIP file for you called OctoPrint-i18n-<locale>-<timestamp>.zip in the translations folder which can be installed by other OctoPrint users. A translation repository similar to the plugin repository will soon be made available to share these language packs, for now it is suggested to upload the file somewhere and announce its availability on the Mailinglist and the G+ Community so others will know about it. Please also link it in this section on the wiki start page!

You can’t perform that action at this time.