Should we move from using underscore as builtin for translations?

[wenzeslaus]

Background

In Python, we use the builtin package to make the translate function generally available global, i.e., a builtin (python/grass/__init__.py):

_builtins.__dict__["_"] = _translate

The issue is that underscore is used for other things in Python, namely the interactive shell uses that to store the last value. This makes the translation function calls fail when used in an interactive console. This also makes the tests fail, although I made an effort to mitigate that with do_doctest_gettext_workaround which resolves at least some of the cases. Another usage of underscore is for an unused variable, so when someone uses that they overwrite the translation function locally and the next translation attempt fails creating confusion when writing new Python tools.

Here is failing code I spotted in the CI. What happens is that latest result is assigned to underscore and so calling _("...") fails with TypeError, here 'bool' object is not callable:

File "etc\python\grass\pygrass\vector\__init__.py", line 631, in grass.pygrass.vector.VectorTopo.rewrite
Failed example:
    test_vect.remove()
Exception raised:
    Traceback (most recent call last):
      File "C:\OSGeo4W\apps\Python312\Lib\doctest.py", line 1368, in __run
        exec(compile(example.source, filename, "single",
      File "<doctest grass.pygrass.vector.VectorTopo.rewrite[20]>", line 1, in <module>
        test_vect.remove()
      File "etc\python\grass\pygrass\vector\abstract.py", line 475, in remove
        utils.remove(self.name, "vect")
      File "etc\python\grass\pygrass\utils.py", line 110, in remove
        grasscore.run_command("g.remove", quiet=True, flags="f", type=maptype, name=oldname)
      File "etc\python\grass\script\core.py", line 588, in run_command
        return handle_errors(returncode, result=None, args=args, kwargs=kwargs)
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "etc\python\grass\script\core.py", line 435, in handle_errors
        raise CalledModuleError(module=module, code=code, returncode=returncode)
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "etc\python\grass\exceptions\__init__.py", line 84, in __init__
        err = _("See errors above the traceback or in the error output.")
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    TypeError: 'bool' object is not callable

If I recall my testing way back when correctly, importing the translation function fixes the problems with conflicts even when keeping the name as underscore.

Question

Should we keep using the translation function as a builtin and fix the individual issues in tests or should we review the whole code base and put there explicit imports of the translation function?

History

The history in reverse chronological order of this is that most recently (2021), I added the lazy loading so that the package can be imported before gettext is set up in f4313c4 (#1838). Before that (2019), bb779c2 (Trac Ticket 3790) made it a builtin as a preparation for never-finished Trac Ticket 3772: Make the grass library importable outside of a GRASS session. This replaced my earlier solution for wxGUI code which went into the opposite direction and made the translate function something to be imported, replacing the original solution using a builtin (which bb779c2 reverted to using a builtin again). The commit for the removal of builtin use in wxGUI is ee95f55 with additional fixes in 1423e79. The Trac Ticket 1739: Language switch on wxGUI doesn't affect all strings (fixed)) has an overview where things were in 2014:

No complains since then, so closing as fixed. Feel free open a new ticket if you encounter any other problems.

Related/unresolved:

• The issue remains for library and modules, follow #2425 [Trac].
• Smaller issue related to toolboxes is inside of #2142 [Trac].
• r57219 has some code duplication (visible in r57220) which should be removed in the future (the solution is probably a separate (wxgui.)translations package/module).

I'm suggesting to go back to the 2014 solution of not using a builtin and instead, have an explicit import anywhere where translation function is needed.

[echoix]

I think that going more explicit would be better. It helps with the principle of less surprise.

Also, I would inspire myself of the practices developed for Django. https://docs.djangoproject.com/en/5.2/topics/i18n/translation/
They have quite good docs for a while, and they explain their reasoning on why they chose this way because of the other approaches. What I find interesting is their lazy loading versions, where the strings aren't translated yet on assignment, only at the last possible time, when displaying. Probably useful for gui code. I'm not sure the Python version has this, but I liked their explanation.

[wenzeslaus]

I was referencing the Django a lot back at these Trac tickets. Using the basic import approach and then going from there sounds good to me.