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.
- Keep placeholders like
%(...)setc 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.
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 :)
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
.pofiles) will become available without having to run
python setup.py installeverytime.
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.
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 install transifex-client
After that all
tx commands should work (see
tx --help or the online help for how to use it).
To pull the current translation of the locale you wish to translate, do
tx pull -l <locale>
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
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:
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.
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!