pallets
Localisation of more strings
Problem and proposal
Using Click in a multi-lingual package, we would like to localise more strings than currently possible.
In our work before this PR, we reach like:
> export LANG=ja_JP.UTF-8
> artefacts hello
Usage: artefacts hello [OPTIONS] プロジェクト名
Try 'artefacts hello --help' for help.
Error: Missing argument 'プロジェクト名'.
The package we develop yields the artefacts command, based on Click, works alright to translate our strings, as well as a range of strings in Click wrapped with gettext.
With this PR, we get:
> export LANG=ja_JP.UTF-8
> artefacts hello
使用法: artefacts hello [OPTIONS] プロジェクト名
ヘルプについては 'artefacts hello --help' を試してください。
エラー：引数がありません 'プロジェクト名'.
Which looks like possibly full coverage of meaningful strings in Click.
Note this PR addresses two issues:
- Several strings where not wrapped into
gettext - Libraries like PyBabel (most users?) cannot work with f-strings, so the pathological approach to use the format method, and to deactivate the PyUpgrade U032 rule (converts to f-strings).
Limitation, side-effects and discussion
It looks like part of this PR may be desired, as localisation is already in place---this mainly covers more of the strings (I'd say all the strings, but localisation does not always make sense).
However in the current approach I had to "deal" with f-strings and PyUpgrade, which may be undesired change for the project. On top of that it seems there is a bug in either Ruff or PyUpgrade in accepting ignore rules on multi-line commands. So a bunch of files get a file-global deactivation of the U032 rule, which means these files will not get checked for f-strings.
F-strings are assumedly desired, but given (1) PyBabel does not and may not support them, and (2) Click is library code, the project may (have to) accept the format method everywhere localisation is needed.
Recent discussions mention f-strings may work in PyBabel from Python 3.12. We did not confirm it, as we want to support down to the oldest supported Python3. So the changed proposed here may be transient for a couple years (then PyUpgrade may be reactivated and let work).
Related work
This PR only aims at localising more strings, so related to i18n issues.
On the way to this PR, we have considered a couple alternatives, notably trying to use the class API of Python's gettext. Some elements of discussion here may be useful to:
- https://github.com/pallets/click/pull/2864 by @v--
- https://github.com/pallets/click/issues/2706 by @carmenbianca
In fact, Carmen's post helped solve an issue in using catalogues from different domains at runtime (thanks!).
Checklist on CONTRIBUTING
- [ ] Add tests that demonstrate the correct behavior of the change. Tests should fail without the change.
- [ ] Add or update relevant docs, in the docs folder and in code.
- [ ] Add an entry in CHANGES.rst summarizing the change and linking to the issue.
- [ ] Add
.. versionchanged::entries in any relevant code docs.
At submission time, nothing checked here, as first would like to make sure this PR target is acceptable (likely not as-is). The tox-based checks all pass, though (i.e. running the tox command returns all green, except the skipped tests).
This PR supersedes #2890, because of a problem with GitHub.
I don't think we are willing to limit the use of f strings in the project at this time. Thoughts @davidism?
For user-facing messages, yes we can use the _("").format() pattern, f-strings can't be used for translation.
The # noqa: UP036 mark does not seem to be needed, please remove this.
We're only translating user-facing messages at this time, not developer-facing. Please remove all such translation markings.
Most of the changes here need to be rolled back, they are not part of the user-facing output.
Hey thanks for the review and feedback. A quick note to let you know I expect to improve the work here soon, most likely in November. Sorry for anyone watching and expecting this sooner.