Localisation of more strings by ic · Pull Request #2902 · pallets/click

ic · 2025-05-12T02:44:03Z

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:

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.

Babel does not support f-strings, which prevents from localising a few strings in the code, like "Usage: " and "Try". The changes in this commit rewrites f-strings into the format syntax. Please note some f-strings remain as they are not expected to be translatable. This commit has to deactivate the UP032 rule on a few files. There seems to be an unreported bug in either Ruff or pyupgrade: The UP032 rule is not deactivated on multi-line commands, including multi-line strings.

…l_support

Please note Windows may requires extra configuration (as it may not set variables expected by gettext). Click does not perform the extra for some reason, and deemed out of scope.

Some f-strings changed to the format method in earlier commits do not need localisation. This commit restores them to reduce the amount of changes.

Rowlando13 · 2025-08-23T08:24:01Z

I don't think we are willing to limit the use of f strings in the project at this time. Thoughts @davidism?

davidism · 2025-08-23T14:37:51Z

+# always force f-strings. The latter are unfortunately not supported yet
+# by Babel, a localisation library.
+#
+# Note: Using `# noqa: UP032` on lines has not worked, so a file


None of these noqa marks are needed. Ruff is not trying to autoupgrade anything if I remove the comments, inline or file-level.

Updated from former Ruff 0.8.1 to the latest 0.14.10, and as you reported, the UP032 do not trigger anymore.

All files cleaned from the comments, as well as the noqa marks.

davidism · 2025-08-23T14:46:04Z

-            f"It is not possible to add the group {cmd_name!r} to another"
-            f" group {base_command.name!r} that is in chain mode."
-        )
+        message = _(


We're only translating user-facing messages at this time, not developer-facing. Please remove all such translation markings.

I have done a pass on all new translations and removed the ones that looked like dev-facing. How does it look now? I am not sure about a couple.

davidism · 2025-08-23T14:46:09Z

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.

davidism · 2025-08-23T14:46:47Z

-                else "(DEPRECATED)"
+                else _("(DEPRECATED)")
            )
            text = _("{text} {deprecated_message}").format(


This shouldn't have ever been marked for translation. It should be removed, since you've added the translation to the proper location above.

davidism · 2025-08-23T14:48:08Z

Most of the changes here need to be rolled back, they are not part of the user-facing output.

ic · 2025-10-15T08:27:22Z

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.

Co-authored-by: Carmen Bianca BAKKER <carmen@carmenbianca.eu>

* After a round of code review from the team. * Possibly incomplete, as based on the author's evaluation of what is for UX and what is for developers.

AndreasBackx

This looks fine now. Though I'd love for someone else to give this a final eye because I've never really touched too much gettext stuff.

ic · 2026-04-30T01:13:28Z

For the record and contribute to the review, we have been using this branch for a year in our CLI, without noticeable problem so far:

The CLI is for robotics engineering: pip install artefacts-cli

# export LANGUAGE=en_GB:en
# artefacts run-remote test_manipulation
Scanning source...
Job data compression: 5/5 Done
Job data uploading:   5/5 Done
Job meta uploading:   3/3 Done
Uploaded 42 MiB of compressed job data and 1 KiB of job metadata.
The new job will show up shortly at https://app.artefacts.com/artefacts/artefacts-toolkit-testsuite

# export LANGUAGE=ja_JP:ja
# artefacts run-remote test_manipulation
ソースをスキャン中...
ジョブデータの圧縮: 5/5 完了
ジョブデータのアップロード:   5/5 完了
ジョブメタデータのアップロード:   3/3 完了
圧縮されたジョブデータ 32 MiB 、およびジョブメタデータ 2 KiB のアップロードが完了しました。
新しいジョブは、まもなく https://app.artefacts.com/artefacts/artefacts-toolkit-testsuite に表示されます。

(if you try the package, the output will differ as working on it, but the translation is in use for a year already)

kdeldycke · 2026-04-30T10:58:28Z

@ic how hard would it be to add a couple of unittests? At least to prove and lockdown that Click is properly translating strings? With unittests we can force future contributors to be aware of this support.

Other than that this PR looks good for inclusion into 8.4.0.

kdeldycke · 2026-04-30T11:10:54Z

        elif errno == ERROR_NOT_ENOUGH_MEMORY:
            return "ERROR_NOT_ENOUGH_MEMORY"
-        return f"Windows error {errno}"
+        return _("Windows error: {error}").format(error=errno)


I like how you unified the Windows error: message string here by adding a colon.

kdeldycke · 2026-04-30T11:45:37Z

        """
        if prefix is None:
-            prefix = f"{_('Usage:')} "
+            prefix = "{usage} ".format(usage=_("Usage:"))


Maybe there is a subtlety I don't get but both f"{_('Usage:')} " and "{usage} ".format(usage=_("Usage:")) looks equivalent to me no?

This is about translation reuse (and not best retrospectively). The translated string has no trailing space. The format adds the space at this place in the code.

Not best, as I usually prefer to not include punctuation as much as possible, like the trailing colon. I did no check, but likely done to reduce the amount of change across the codebase.

kdeldycke · 2026-04-30T11:51:10Z

Grepping through the code I just realized some default strings are not translated, like in:

click/src/click/decorators.py

Lines 399 to 400 in 831c8f0

    
           kwargs.setdefault("prompt", "Do you want to continue?") 
        
           kwargs.setdefault("help", "Confirm the action without prompting.")

click/src/click/core.py

Lines 1139 to 1143 in 831c8f0

    
           deprecated_message = ( 
        
               f"(DEPRECATED: {self.deprecated})" 
        
               if isinstance(self.deprecated, str) 
        
               else "(DEPRECATED)" 
        
           )

click/src/click/core.py

Lines 2786 to 2790 in 831c8f0

    
           deprecated_message = ( 
        
               f"(DEPRECATED: {deprecated})" 
        
               if isinstance(deprecated, str) 
        
               else "(DEPRECATED)" 
        
           )

click/src/click/core.py

Lines 2600 to 2607 in 831c8f0

    
           message = _( 
        
               "DeprecationWarning: The {param_type} {name!r} is deprecated." 
        
               "{extra_message}" 
        
           ).format( 
        
               param_type=self.param_type_name, 
        
               name=self.human_readable_name, 
        
               extra_message=extra_message, 
        
           )

click/src/click/termui.py

Line 258 in 831c8f0

"y/n" if default is None else ("Y/n" if default else "y/N"),

click/src/click/termui.py

Lines 266 to 269 in 831c8f0

    
           if value in ("y", "yes"): 
        
               rv = True 
        
           elif value in ("n", "no"): 
        
               rv = False

ic · 2026-05-01T00:15:41Z

@kdeldycke Thank you for the round of review.

Unit test, on it starting today. It looks like I can come up with some next week.
Translation strings like Usage: are often better be usage and let the code format and punctuate. Not done to minimise code change, but personal preference and suggestion, perhaps a later PR.
The default strings you list up should be included. Two questions:

The PR is one year old, and some may be new strings. If acceptable, perhaps working first toward merging this PR, then iterate? As writing tests by next week, the ones you found can be done at the same time.
An earlier comment by @davidism points out some strings are for developers only and should not be translated. It makes sense to me as dev is done in English anyway. It looks like only 2 of the ones you found enter this category. Best if we can confirm before I make us oscillating change/review.

ic added 7 commits April 30, 2025 14:54

Merge branch 'babel_support' of github.com:art-e-fact/click into babe…

be2f41c

…l_support

Add missing localisation wrappers

4768c98

Please note Windows may requires extra configuration (as it may not set variables expected by gettext). Click does not perform the extra for some reason, and deemed out of scope.

Restore more f-strings that do not need localisation

74d7795

Some f-strings changed to the format method in earlier commits do not need localisation. This commit restores them to reduce the amount of changes.

Merge branch 'main' into babel_support

aadd7e1

Fix formatting based on palllets/click main

caf571b

Rowlando13 marked this pull request as draft August 23, 2025 08:24

davidism reviewed Aug 23, 2025

View reviewed changes

carmenbianca reviewed Oct 15, 2025

View reviewed changes

Comment thread src/click/_termui_impl.py

ic and others added 5 commits December 29, 2025 15:46

Update src/click/_termui_impl.py

3814431

Co-authored-by: Carmen Bianca BAKKER <carmen@carmenbianca.eu>

Merge remote-tracking branch 'origin/main' into babel_support

0ed80fb

Remove translation on developer strings

8843726

* After a round of code review from the team. * Possibly incomplete, as based on the author's evaluation of what is for UX and what is for developers.

Merge branch 'art-e-fact:babel_support' into babel_support

4c0f5b7

Fixes on self-CR

68a052f

ic commented Dec 29, 2025

View reviewed changes

Comment thread src/click/types.py

Fix after self-review

18b8918

ic requested review from carmenbianca and davidism December 29, 2025 07:48

ic marked this pull request as ready for review January 6, 2026 00:01

kdeldycke changed the base branch from main to stable April 16, 2026 09:33

kdeldycke added the docs label Apr 21, 2026

AndreasBackx approved these changes Apr 30, 2026

View reviewed changes

kdeldycke added this to the 8.4.0 milestone Apr 30, 2026

kdeldycke added the f:help feature: help text label Apr 30, 2026

kdeldycke changed the base branch from stable to main April 30, 2026 10:53

kdeldycke requested review from Rowlando13 and removed request for carmenbianca April 30, 2026 10:53

kdeldycke reviewed Apr 30, 2026

View reviewed changes

Merge branch 'main' into babel_support

9e90ad9

Uh oh!

Conversation

ic commented May 12, 2025

Problem and proposal

Limitation, side-effects and discussion

Related work

Checklist on CONTRIBUTING

Uh oh!

Rowlando13 commented Aug 23, 2025

Uh oh!

davidism Aug 23, 2025

Choose a reason for hiding this comment

Uh oh!

ic Dec 29, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

davidism Aug 23, 2025

Choose a reason for hiding this comment

Uh oh!

ic Dec 29, 2025

Choose a reason for hiding this comment

Uh oh!

davidism commented Aug 23, 2025

Uh oh!

davidism Aug 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ic Dec 29, 2025

Choose a reason for hiding this comment

Uh oh!

davidism commented Aug 23, 2025

Uh oh!

ic commented Oct 15, 2025

Uh oh!

Uh oh!

Uh oh!

AndreasBackx left a comment

Choose a reason for hiding this comment

Uh oh!

ic commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

kdeldycke commented Apr 30, 2026

Uh oh!

kdeldycke Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

kdeldycke Apr 30, 2026

Choose a reason for hiding this comment

Uh oh!

ic May 1, 2026

Choose a reason for hiding this comment

Uh oh!

kdeldycke commented Apr 30, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ic commented May 1, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

ic Dec 29, 2025 •

edited

Loading

davidism Aug 23, 2025 •

edited

Loading

ic commented Apr 30, 2026 •

edited

Loading

kdeldycke commented Apr 30, 2026 •

edited

Loading