refactor: keep list help in the literal help text blocks (#1327)

## ℹ️ Description

Follow-up to #1321. The CLI help text is the one place that keeps a
complete English and a complete German text block in the code, so `list`
belongs into both blocks instead of using a gettext lookup with a
temporary locale switch. Related issue: none.

## 📋 Changes Summary

- Write the `list` help line literally into the English and German
blocks of `help_text()` and drop the locale switch and the `help_text`
entry in `translations.de.yaml`.
- Replace the locale-preservation test with a simple check of the `list`
line per language.
- Document the exception for the CLI help text in `CONTRIBUTING.md`.

No dependencies or configuration changes.

### ⚙️ Type of Change

- [ ] 🐞 Bug fix (non-breaking change which fixes an issue)
- [ ] ✨ New feature (adds new functionality without breaking existing
usage)
- [ ] 💥 Breaking change (changes that might break existing user setups,
scripts, or configurations)

Refactoring only, no user-visible change: the help output is identical.

## ✅ Checklist

- [x] I have reviewed my changes to ensure they meet the project's
standards.
- [x] I have tested my changes and ensured that all tests pass (`pdm run
utest` locally, the full suite runs in CI).
- [x] I have formatted the code (`pdm run format`).
- [x] I have verified that linting passes (`pdm run lint`).
- [x] I have updated documentation where necessary.

By submitting this pull request, I confirm that you can use, modify,
copy, and redistribute this contribution, under the terms of your
choice.


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

* **Bug Fixes**
* CLI help now displays the complete English or German text for the
`list` command, regardless of the currently active language setting.
* **Documentation**
* Updated translation guidance to clarify that CLI help text should
include complete English and German wording.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->
This commit is contained in:
Jens authored and GitHub committed 2026-10-06 13:05:11 +02:00
1 parent ab79e10c93
commit b9daab1121
4 files changed
+6 -22

No files matched your search

+1 -1
View File
@@ -339,6 +339,6 @@ See the [LICENSE.txt](LICENSE.txt) file for our project's licensing. All source
- For every user-facing message, a **German translation** must be added to `src/kleinanzeigen_bot/resources/translations.de.yaml`.
- Log messages are auto-translated by `TranslatingLogger`; do not wrap `LOG.*`/`logger.*` message strings with `_()`.
- Non-log user-facing strings (e.g., `print`, `ainput`, exceptions, validation messages) should use `_()`.
- Use the translation system for all output—**never hardcode German or other languages** in the code.
- Use the translation system for all output—**never hardcode German or other languages** in the code. The one exception is the CLI help text (`help_text()` in `cli.py`), which keeps a complete English and a complete German text block; add new commands and options to both blocks instead of using `_()`.
- If you add or change a user-facing message, update the translation file and ensure that translation completeness tests pass (`tests/unit/test_translations.py`).
- Review the translation guidelines and patterns in the codebase for correct usage.
+3 -11
View File
@@ -19,7 +19,6 @@ import signal
import sys
import textwrap
from dataclasses import dataclass
from gettext import gettext as _
from pathlib import Path
from typing import TYPE_CHECKING, Final
@@ -140,15 +139,8 @@ def _help_executable() -> str:
def help_text(*, executable:str | None = None, language:str | None = None) -> str:
"""Render CLI help in the requested language without changing the current locale."""
exe = executable if executable is not None else _help_executable()
current_locale = get_current_locale()
lang = language if language is not None else current_locale.language
try:
set_current_locale(Locale(lang))
list_description = _("lists current online ads with ID, title, state, and expiry date")
finally:
set_current_locale(current_locale)
lang = language if language is not None else get_current_locale().language
if lang == "de":
return textwrap.dedent(
f"""\
@@ -170,7 +162,7 @@ def help_text(*, executable:str | None = None, language:str | None = None) -> st
create-config - Erstellt eine neue Standard-Konfigurationsdatei, falls noch nicht vorhanden
diagnose - Diagnostiziert Browser-Verbindungsprobleme und zeigt Troubleshooting-Informationen
status - Zeigt Anzeigenstatus und APR-Vorschau an
list - {list_description}
list - Zeigt aktuelle Online-Anzeigen mit ID, Titel, Status und Ablaufdatum an
--
help - Zeigt diese Hilfe an (Standardbefehl)
version - Zeigt die Version der Anwendung an
@@ -235,7 +227,7 @@ def help_text(*, executable:str | None = None, language:str | None = None) -> st
create-config - creates a new default configuration file if one does not exist
diagnose - diagnoses browser connection issues and shows troubleshooting information
status - shows ad status and APR preview details
list - {list_description}
list - lists current online ads with ID, title, state, and expiry date
--
help - displays this help (default command)
version - displays the application version
@@ -30,9 +30,6 @@ kleinanzeigen_bot/captcha_flow.py:
#################################################
kleinanzeigen_bot/cli.py:
#################################################
help_text:
"lists current online ads with ID, title, state, and expiry date": "Zeigt aktuelle Online-Anzeigen mit ID, Titel, Status und Ablaufdatum an"
parse_args:
"Use --help to display available options.": "Mit --help können die verfügbaren Optionen angezeigt werden."
"Unknown command: %s": "Unbekannter Befehl: %s"
+2 -7
View File
@@ -108,18 +108,13 @@ def test_list_is_accepted_and_documented() -> None:
assert "list -" in help_text(language = "de")
@pytest.mark.parametrize("initial_language", ["en", "de"])
@pytest.mark.parametrize(("language", "description"), [
("en", "lists current online ads with ID, title, state, and expiry date"),
("de", "Zeigt aktuelle Online-Anzeigen mit ID, Titel, Status und Ablaufdatum an"),
])
def test_list_help_honors_explicit_language_and_preserves_locale(initial_language:str, language:str, description:str) -> None:
"""Honor the requested help language without changing the caller locale."""
locale = i18n.Locale(initial_language, "TEST")
i18n.set_current_locale(locale)
def test_list_help_is_rendered_in_requested_language(language:str, description:str) -> None:
"""Describe the list command in the requested help language."""
assert f"list - {description}" in help_text(language = language)
assert i18n.get_current_locale() == locale
@pytest.mark.asyncio