refactor: improve language normalization and date handling utilities

- Introduced a new `normalize_lang` function to standardize language codes across the application, ensuring consistent handling of user language preferences.
- Refactored date handling utilities by adding `parse_utc_iso` and `parse_utc_iso_naive` functions for better parsing of ISO 8601 date strings, enhancing timezone awareness.
- Updated various modules to utilize the new language normalization and date parsing functions, improving code clarity and maintainability.
- Enhanced error handling in date validation to raise specific `DateRangeValidationError` exceptions, providing clearer feedback on validation issues.
- Improved test coverage for date range validation and language normalization functionalities, ensuring robustness and reliability.

duty_teller/api/personal_calendar_ics.py

@@ -5,6 +5,7 @@ from datetime import datetime, timezone
 from icalendar import Calendar, Event
 
 from duty_teller.db.models import Duty
+from duty_teller.utils.dates import parse_utc_iso
 
 # Summary labels by event_type (duty | unavailable | vacation)
 SUMMARY_BY_TYPE: dict[str, str] = {
@@ -14,16 +15,6 @@ SUMMARY_BY_TYPE: dict[str, str] = {
 }
 
 
-def _parse_utc_iso(iso_str: str) -> datetime:
-    """Parse ISO 8601 UTC string (e.g. 2025-01-15T09:00:00Z) to timezone-aware datetime."""
-    s = iso_str.strip().rstrip("Z")
-    if "Z" in s:
-        s = s.replace("Z", "+00:00")
-    else:
-        s = s + "+00:00"
-    return datetime.fromisoformat(s)
-
-
 def build_personal_ics(duties_with_name: list[tuple[Duty, str]]) -> bytes:
     """Build a VCALENDAR (ICS) with one VEVENT per duty.
 
@@ -41,8 +32,8 @@ def build_personal_ics(duties_with_name: list[tuple[Duty, str]]) -> bytes:
 
     for duty, _full_name in duties_with_name:
         event = Event()
-        start_dt = _parse_utc_iso(duty.start_at)
-        end_dt = _parse_utc_iso(duty.end_at)
+        start_dt = parse_utc_iso(duty.start_at)
+        end_dt = parse_utc_iso(duty.end_at)
         # Ensure timezone-aware for icalendar
         if start_dt.tzinfo is None:
             start_dt = start_dt.replace(tzinfo=timezone.utc)