Internationalization - Proof of Concept

default_config.json

@@ -8,6 +8,7 @@
         "gps_lock": false,
         "timezone": "America/Los_Angeles"
     },
+    "language": "en",
     "camera_exp": 400000,
     "camera_gain": 20,
     "menu_anim_speed": 0.1,

docs/source/dev_guide.rst

@@ -76,6 +76,22 @@ You can then use the supplied ``Makefile`` to build a html tree using ``make htm
     cd build/html; python -m http.server
 
 
+Internationalization
+-----------------------
+
+PiFinder uses ``gettext`` and ``pybabel`` for internationalization.
+You can find the information in folder ``python/locale`` in the repository. 
+This means that strings that need translation must be 
+enclosed in a call to ``_()`` such als ``_("string that needs translation")``. 
+
+As we would like to allow users to switch the language of the user interface from the menu, and with-out restarting PiFinder,
+care must be taken, that translations are performed dynamically, i.e. not at load time of python files. 
+If you have a variable at package level that needs to be translated, you still need to mark the strings with ``_()``, but make sure 
+it is not translated by overriding the ``_()``-function with a local one, that returns the string and then ``del`` that from the context, when you're done.
+You can find an example of this in ``menu_structure.py`` at the top and bottom of the file. 
+
+Please also check your unit tests, that these take care of installing ``_()`` into the local context. (We have not had that case yet.)
+
 Setup the development environment
 ---------------------------------
 
@@ -190,6 +206,13 @@ The defined sessions are:
   session is not run by default, but is executed on code check in to the PiFinder
   repository.
 
+- babel -> Runs the complete toolchain for internationalization (based on `pybabel`).
+  That means extracts strings to translate and updates the `.po`-files in `python/locale/**`
+  Then these are compiled into `.mo`-files. Unfortuntely, this changes the `.mo`-files in any case,
+  even if the there have been no changes to strings or their translation. As this will show up 
+  as changes to checked-in, this is not run by default. 
+
+
 CI/CD
 .......
 

python/PiFinder/main.py

@@ -10,6 +10,8 @@
 
 """
 
+import gettext
+
 import os
 
 # skyfield performance fix, see: https://rhodesmill.org/skyfield/accuracy-efficiency.html
@@ -51,6 +53,12 @@
 from PiFinder.calc_utils import sf_utils
 from PiFinder.displays import DisplayBase, get_display
 
+# Install the _("text") into global context for Internationalization
+# On RasPi/Ubuntu the default locale is C.utf8, see `locale -a`, which locales are available
+# You need to install `apt install language-pack_xx`, where xx is the ISO country code.
+# Passing nothing as third parameter means the language is determined from environment variables (e.g. LANG)
+gettext.install("PiFinder", "locale")
+
 logger = logging.getLogger("main")
 
 hardware_platform = "Pi"
@@ -287,6 +295,13 @@ def main(
     screen_brightness = cfg.get_option("display_brightness")
     set_brightness(screen_brightness, cfg)
 
+    # Set user interface language
+    lang = cfg.get_option("language")
+    langXX = gettext.translation(
+        "messages", "locale", languages=[lang], fallback=(lang == "en")
+    )
+    langXX.install()
+
     import PiFinder.manager_patch as patch
 
     patch.apply()
@@ -735,6 +750,10 @@ def rotate_logs() -> Path:
     return utils.data_dir / "pifinder.log"
 
 
+#############################################################################################
+#############################################################################################
+#############################################################################################
+
 if __name__ == "__main__":
     print("Bootstrap logging configuration ...")
     logging.basicConfig(format="%(asctime)s BASIC %(name)s: %(levelname)s %(message)s")
@@ -816,6 +835,11 @@ def rotate_logs() -> Path:
         "-x", "--verbose", help="Set logging to debug mode", action="store_true"
     )
     parser.add_argument("-l", "--log", help="Log to file", action="store_true")
+    parser.add_argument(
+        "--lang",
+        help="Force user interface language (iso2 code). Changes configuration",
+        type=str,
+    )
     args = parser.parse_args()
     # add the handlers to the logger
     if args.verbose:
@@ -863,7 +887,13 @@ def rotate_logs() -> Path:
     elif args.keyboard.lower() == "none":
         from PiFinder import keyboard_none as keyboard  # type: ignore[no-redef]
 
-        rlogger.warn("using no keyboard")
+        rlogger.warning("using no keyboard")
+
+    if args.lang:
+        if args.lang.lower() not in ["en", "de", "fr", "es"]:
+            raise Exception(f"Unknown language '{args.lang}' passed via command line.")
+        else:
+            config.Config().set_option("language", args.lang)
 
     # if args.log:
     #    datenow = datetime.datetime.now()

python/PiFinder/solver.py

@@ -69,11 +69,17 @@ def solver(
                 + shared_state.arch()
             )
         except FileNotFoundError as e:
-            logger.warn(
+            logger.warning(
                 "Not using cedar_detect, as corresponding file '%s' could not be found",
                 e.filename,
             )
             cedar_detect = None
+        except ValueError as e:
+            logger.warning(
+                "Not using cedar_detect, as the binary path could not be determined: %s",
+                e,
+            )
+            cedar_detect = None
 
         try:
             while True:

python/PiFinder/ui/align.py

@@ -53,7 +53,7 @@ def align_on_radec(ra, dec, command_queues, config_object, shared_state) -> bool
                     dec,
                 ]
             )
-            command_queues["console"].put("Align Timeout")
+            command_queues["console"].put(_("Align Timeout"))
             return False
 
         try:
@@ -71,7 +71,7 @@ def align_on_radec(ra, dec, command_queues, config_object, shared_state) -> bool
         return False
 
     # success, set all the things...
-    command_queues["console"].put("Alignment Set")
+    command_queues["console"].put(_("Alignment Set"))
     shared_state.set_solve_pixel(target_pixel)
     config_object.set_option("solve_pixel", target_pixel)
     return True
@@ -211,13 +211,13 @@ def update(self, force=False):
             )
             self.draw.text(
                 (self.display_class.titlebar_height + 2, 20),
-                "Can't plot",
+                _("Can't plot"),
                 font=self.fonts.large.font,
                 fill=self.colors.get(255),
             )
             self.draw.text(
                 (self.display_class.titlebar_height + 2 + self.fonts.large.height, 50),
-                "No Solve Yet",
+                _("No Solve Yet"),
                 font=self.fonts.base.font,
                 fill=self.colors.get(255),
             )
@@ -330,17 +330,17 @@ def key_square(self):
             self.align_mode = False
 
             if self.alignment_star is not None:
-                self.message("Aligning...", 0.1)
+                self.message(_("Aligning..."), 0.1)
                 if align_on_radec(
                     self.alignment_star["ra_degrees"],
                     self.alignment_star["dec_degrees"],
                     self.command_queues,
                     self.config_object,
                     self.shared_state,
                 ):
-                    self.message("Aligned!", 1)
+                    self.message(_("Aligned!"), 1)
                 else:
-                    self.message("Failed", 2)
+                    self.message(_("Alignment failed"), 2)
         else:
             self.align_mode = True
         self.update(force=True)

python/PiFinder/ui/base.py

@@ -17,6 +17,12 @@
 from PiFinder.config import Config
 from PiFinder.ui.marking_menus import MarkingMenu
 from PiFinder.catalogs import Catalogs
+from typing import Any, TYPE_CHECKING
+
+if TYPE_CHECKING:
+
+    def _(a) -> Any:
+        return a
 
 
 class UIModule:
@@ -191,7 +197,9 @@ def screen_update(self, title_bar=True, button_hints=True) -> None:
                     (6, 1), str(self.fps), font=self.fonts.bold.font, fill=fg
                 )
             else:
-                self.draw.text((6, 1), self.title, font=self.fonts.bold.font, fill=fg)
+                self.draw.text(
+                    (6, 1), _(self.title), font=self.fonts.bold.font, fill=fg
+                )
             imu = self.shared_state.imu()
             moving = True if imu and imu["pos"] and imu["moving"] else False
 

python/PiFinder/ui/callbacks.py

@@ -10,11 +10,19 @@
 
 import datetime
 import logging
+import gettext
 
+from typing import Any, TYPE_CHECKING
 from PiFinder import utils
 from PiFinder.ui.base import UIModule
 from PiFinder.catalogs import CatalogFilter
 
+if TYPE_CHECKING:
+
+    def _(a) -> Any:
+        return a
+
+
 sys_utils = utils.get_sys_utils()
 
 
@@ -40,7 +48,7 @@ def reset_filters(ui_module: UIModule) -> None:
 
     ui_module.catalogs.set_catalog_filter(new_filter)
     ui_module.catalogs.filter_catalogs()
-    ui_module.message("Filters Reset")
+    ui_module.message(_("Filters Reset"))
     ui_module.remove_from_stack()
     return
 
@@ -51,10 +59,10 @@ def activate_debug(ui_module: UIModule) -> None:
     add fake gps info
     """
     ui_module.command_queues["camera"].put("debug")
-    ui_module.command_queues["console"].put("Debug: Activated")
+    ui_module.command_queues["console"].put(_("Debug: Activated"))
     dt = datetime.datetime(2024, 6, 1, 2, 0, 0)
     ui_module.shared_state.set_datetime(dt)
-    ui_module.message("Test Mode")
+    ui_module.message(_("Test Mode"))
 
 
 def set_exposure(ui_module: UIModule) -> None:
@@ -70,7 +78,7 @@ def shutdown(ui_module: UIModule) -> None:
     """
     shuts down the Pi
     """
-    ui_module.message("Shutting Down", 10)
+    ui_module.message(_("Shutting Down"), 10)
     sys_utils.shutdown()
 
 
@@ -79,32 +87,32 @@ def restart_pifinder(ui_module: UIModule) -> None:
     Uses systemctl to restart the PiFinder
     service
     """
-    ui_module.message("Restarting...", 2)
+    ui_module.message(_("Restarting..."), 2)
     sys_utils.restart_pifinder()
 
 
 def restart_system(ui_module: UIModule) -> None:
     """
     Restarts the system
     """
-    ui_module.message("Restarting...", 2)
+    ui_module.message(_("Restarting..."), 2)
     sys_utils.restart_system()
 
 
 def switch_cam_imx477(ui_module: UIModule) -> None:
-    ui_module.message("Switching cam", 2)
+    ui_module.message(_("Switching cam"), 2)
     sys_utils.switch_cam_imx477()
     restart_system(ui_module)
 
 
 def switch_cam_imx296(ui_module: UIModule) -> None:
-    ui_module.message("Switching cam", 2)
+    ui_module.message(_("Switching cam"), 2)
     sys_utils.switch_cam_imx296()
     restart_system(ui_module)
 
 
 def switch_cam_imx462(ui_module: UIModule) -> None:
-    ui_module.message("Switching cam", 2)
+    ui_module.message(_("Switching cam"), 2)
     sys_utils.switch_cam_imx462()
     restart_system(ui_module)
 
@@ -127,14 +135,25 @@ def get_camera_type(ui_module: UIModule) -> list[str]:
     return [cam_id]
 
 
+def switch_language(ui_module: UIModule) -> None:
+    iso2_code = ui_module.config_object.get_option("language")
+    msg = str(f"Language: {iso2_code}")
+    ui_module.message(_(msg))
+    lang = gettext.translation(
+        "messages", "locale", languages=[iso2_code], fallback=(iso2_code == "en")
+    )
+    lang.install()
+    logger.info("Switch Language: %s", iso2_code)
+
+
 def go_wifi_ap(ui_module: UIModule) -> None:
-    ui_module.message("WiFi to AP", 2)
+    ui_module.message(_("WiFi to AP"), 2)
     sys_utils.go_wifi_ap()
     restart_system(ui_module)
 
 
 def go_wifi_cli(ui_module: UIModule) -> None:
-    ui_module.message("WiFi to Client", 2)
+    ui_module.message(_("WiFi to Client"), 2)
     sys_utils.go_wifi_cli()
     restart_system(ui_module)
 

python/PiFinder/ui/chart.py

@@ -2,7 +2,7 @@
 # -*- coding:utf-8 -*-
 # mypy: ignore-errors
 """
-This module contains all the UI Module classes
+This module contains the chart (starfield + constellation lines) UI Module class
 
 """
 
@@ -202,13 +202,13 @@ def update(self, force=False):
             )
             self.draw.text(
                 (self.display_class.titlebar_height + 2, 20),
-                "Can't plot",
+                _("Can't plot"),
                 font=self.fonts.large.font,
                 fill=self.colors.get(255),
             )
             self.draw.text(
                 (self.display_class.titlebar_height + 2 + self.fonts.large.height, 50),
-                "No Solve Yet",
+                _("No Solve Yet"),
                 font=self.fonts.base.font,
                 fill=self.colors.get(255),
             )