Skip to content

Internationalization

This page documents how to manage translation catalogs for the plugin (Python and JavaScript strings) and the typical pybabel workflow used in this repository.

Locations

  • Python templates and code: octoprint_uptime/translations/ (contains locale subfolders with LC_MESSAGES/messages.po and compiled .mo).
  • Project-level translations (used for packaging/documentation): top-level translations/ (also contains de and en locale folders).
  1. Extract translatable strings into a POT file:
# using the venv-binary if you have a project virtualenv
./venv/bin/pybabel extract -F babel.cfg -o translations/messages.pot .
  1. Update each language catalog from the new POT:
./venv/bin/pybabel update -i translations/messages.pot -d octoprint_uptime/translations
./venv/bin/pybabel update -i translations/messages.pot -d translations

  1. Edit the .po files in the respective LC_MESSAGES folders and add translations.

  2. Compile .po into binary .mo files for runtime use:

./venv/bin/pybabel compile -d octoprint_uptime/translations
./venv/bin/pybabel compile -d translations

Notes and tips

  • JavaScript extraction: ensure JSDoc or gettext calls in JS are discoverable by your babel.cfg. In this project, scripts/generate-jsdocs.sh generates docs/api/javascript.md (not committed). JS gettext strings should be included in pybabel extract if configured in babel.cfg.
  • Fuzzy entries: When merging new POTs you may find #, fuzzy flags. Review and remove fuzzy from entries that are correct, and translate the rest.
  • Obsolete entries (#~): These are removed when you update catalogs from a fresh POT; review before deleting if you want to keep historical context.
  • Testing: After compiling, test the plugin in a development OctoPrint instance and check that localized strings appear in the UI and that the .mo files are present in octoprint_uptime/translations/<lang>/LC_MESSAGES/messages.mo.

Troubleshooting

  • If pybabel isn't installed in your environment run pip install Babel or install into the project virtualenv used by development.
  • If compiled .mo files are not loaded at runtime, confirm the plugin package includes the translations directory (check MANIFEST.in and packaging config).