P-039: Django i18n — bilingual UI (tracking)

[dholbach]

Tracking issue for P-039: make all user-facing UI text translatable via Django's i18n framework so the app can run in German or English without code changes.

Scaffold (done in #67)

• LocaleMiddleware, LANGUAGES, LOCALE_PATHS in settings
• django.conf.urls.i18n wired up
• gettext in Dockerfile
• locale/de/ and locale/en/ directories
• {% load i18n %} + lang= attribute in base.html
• ./dev.py i18n command
• inquiry_confirm_delete.html — reference implementation

Language switcher

• DE/EN toggle button in nav bar (feat(i18n): add language switcher toggle to nav (P-039) #68)

Templates (~50 remaining)

Each template needs {% load i18n %} + {% trans %} / {% blocktrans %} on all UI strings, then English msgstr values in locale/en/LC_MESSAGES/django.po.

See inquiry_confirm_delete.html as the reference implementation.
Run ./dev.py i18n after wrapping each template to extract and compile strings.

• Per-template issues to be filed (good first issue — one per template)

Python-side (medium complexity)

• messages.*() calls in views → _() wrappers
• Form labels / help_text → _() wrappers
• Model verbose_name / help_text → _() wrappers
• Admin labels → _() wrappers

Notes

• German is the primary language — DE strings stay as-is; EN needs translation in .po files
• .po source files are committed; .mo compiled files are gitignored (generated locally)
• Language switching uses a session cookie via LocaleMiddleware — no URL prefix needed

[dholbach]

Status update — 2026-06-23

Strategy (adopted)

Rather than a dedicated wrapping sprint, we wrap templates opportunistically as we touch them for any other reason. This is encoded in CLAUDE.md:

Any template touched for any reason must be fully wrapped with {% load i18n %} and {% trans %}/{% blocktrans %} in the same commit.

This avoids a big-bang migration and ensures steady progress without blocking other work.

i18n machinery — what's wired up

• LocaleMiddleware active; language switching via session cookie (no URL prefix)
• {% load i18n %} + lang="{{ LANGUAGE_CODE }}" in base.html — all extending templates inherit the attribute
• locale/de/LC_MESSAGES/django.po — German translations as msgstr
• locale/en/LC_MESSAGES/django.po — identity translations (msgid == msgstr)
• .mo files compiled during Docker image build (compilemessages in Dockerfile)
• ./dev.py i18n — extract + compile in one command
• Convention: English strings as msgids in templates ({% trans "Save" %}), German text lives only in the .po file

PDF templates — permanently exempt

These 5 templates handle language per-document (client language field), not via Django i18n:

• invoice_pdf_base.css, invoice_pdf_de.html, invoice_pdf_en.html
• treatment_contract_pdf.html, intake_form_pdf.html

Templates wrapped so far (5 / 86)

Template	Wrapped in
base.html	#67 (scaffold)
my_practice/inquiry_confirm_delete.html	#81
my_practice/practice_management.html	#81
includes/capacity_monitoring_widget_content.html	#81
my_practice/client_detail_tabs.html	#89

Remaining (~81 templates)

Not tracked individually — they get wrapped as touched. The ./dev.py i18n command after each change keeps the .po catalogs in sync.

[dholbach]

Progress today (v0.2.5) since the last issue update:

• Then: 5 / 86 templates wrapped
• Now: 8 / 90 templates wrapped (4 PDF templates are permanently exempt, so effectively 8 / 86)

Three new templates were wrapped (opportunistic rule in action):

• practice_form.html — touched when adding the booking URL field
• inquiry_form.html — touched for inquiry UX improvements
• session_log_form.html — touched during cockpit work
• client_detail.html — touched during cockpit work (that's actually the 4th new one)

So 8 down, ~78 to go at the current opportunistic pace. The issue was at ~6% coverage three days ago and is now at ~9%.

[dholbach]

Status update — 2026-06-29 (v0.2.6)

Templates: 9 / 86 wrapped (~10%)

One new template since last update:

Template	Wrapped in
my_practice/client_list_cards.html	#106

Running total:

Template	Wrapped in
base.html	#67 (scaffold)
my_practice/inquiry_confirm_delete.html	#81
my_practice/practice_management.html	#81
includes/capacity_monitoring_widget_content.html	#81
my_practice/client_detail_tabs.html	#89
my_practice/practice_form.html	#100
my_practice/inquiry_form.html	#100
my_practice/session_log_form.html	#102
my_practice/client_detail.html	#103 / #104
my_practice/client_list_cards.html	#106

Python views: 3 files fully wrapped (new territory)

CLAUDE.md was extended this session: any Python file touched for any reason must have its user-facing strings wrapped with gettext_lazy as _ or gettext as _. This covers messages.*() calls, JsonResponse error/success values, and form error strings.

Three view files wrapped in this batch:

File	Wrapped in	Notes
client_views.py	#106	gettext_lazy; sentinel "Keine Sitzungen" → None to avoid translation/comparison conflict
clinical_views.py	#107	gettext as _; fixed _ shadowing from session, _ = get_or_create(...) → _created
invoice_views.py	#108	gettext_lazy + ngettext for plurals; same _created fix; format_html for the linked invoice message

Still pending (opportunistic)

• ~77 remaining templates — wrapped as touched
• Form labels / help_text, model verbose_name, admin labels — deferred (see original issue)

[dholbach]

Templates: 18 / 87 wrapped (~21%)

Correction: inquiry_confirm_delete.html was marked done in the previous update but is not actually wrapped — correcting the count.

Two new templates since last update:

Template	Wrapped in
my_practice/inquiry_convert_confirm.html	#161
my_practice/practice_form.html	#100 (already in list — also gains capacity periods section, i18n included)

Running total (18 wrapped):

Template	Wrapped in
base.html	#67 (scaffold)
includes/capacity_monitoring_widget_content.html	#81
includes/client_card.html	—
my_practice/practice_management.html	#81
my_practice/inquiry_form.html	#100
my_practice/practice_form.html	#100
my_practice/session_log_form.html	#102
my_practice/client_detail.html	#103 / #104
my_practice/client_detail_tabs.html	#89
my_practice/client_list_cards.html	#106
my_practice/analytics.html	—
my_practice/client_intake.html	—
my_practice/dashboard.html	—
my_practice/gebueh_leistung_form.html	—
my_practice/includes/heatmap.html	—
my_practice/inquiry_list.html	—
my_practice/invoice_detail.html	—
my_practice/inquiry_convert_confirm.html	#161

69 templates still unwrapped.

Python views: 5 files fully wrapped

File	Wrapped in	Notes
client_views.py	#106	gettext_lazy
clinical_views.py	#107	gettext as _
invoice_views.py	#108	gettext_lazy + ngettext for plurals
practice_views.py	#162	gettext as _; f-strings → %-format
forms.py	#162	gettext_lazy; label/help_text on DateFormField declarations

Still pending

• ~69 remaining templates — wrapped opportunistically as touched
• Model verbose_name / help_text, admin labels — still deferred