agdar/PATIENT_LANGUAGE_IMPLEMENTATION.md

Patient Name Language-Aware Implementation

Summary

This document describes the implementation of language-aware patient name display and LTR phone number formatting across the entire AgdarCentre project.

Changes Made

1. Created Custom Template Tags (core/templatetags/patient_tags.py)

Created a new Django template tag library with the following components:

Template Tags:

• patient_name: Returns patient's full name based on current language

  • Returns full_name_ar when language is Arabic ('ar')
  • Returns full_name_en for all other languages

• patient_first_name: Returns patient's first name based on current language

  • Returns first_name_ar when language is Arabic ('ar')
  • Returns first_name_en for all other languages

• patient_last_name: Returns patient's last name based on current language

  • Returns last_name_ar when language is Arabic ('ar')
  • Returns last_name_en for all other languages

Template Filter:

• ltr: Wraps content in <span dir="ltr"> to force left-to-right display
  • Used for phone numbers to ensure they always display LTR even in Arabic mode

2. Updated Template Files

Total Files Updated: 85 templates

The update script automatically:

1. Added {% load patient_tags %} to templates that reference patient data
2. Replaced all instances of patient.full_name_en with {% patient_name patient %}
3. Replaced all instances of *.patient.full_name_en with {% patient_name *.patient %}
4. Replaced combinations like {{ patient.first_name_en }} {{ patient.last_name_en }} with {% patient_name patient %}
5. Added |ltr filter to all phone number displays

Key Template Categories Updated:

• Core templates: patient_detail.html, patient_card.html, patient_list_partial.html
• Appointments: All appointment-related templates
• Medical: Consultation and follow-up templates
• Nursing: Encounter templates
• SLP: Assessment, intervention, and progress templates
• OT: Session and consultation templates
• ABA: Consultation and behavior tracking templates
• Finance: Invoice and payment templates
• Referrals: Referral templates

3. Usage Examples

In Templates:

{% load i18n patient_tags %}

<!-- Display patient name (language-aware) -->
<h1>{% patient_name patient %}</h1>

<!-- Display phone number (always LTR) -->
<p>Phone: {{ patient.phone|ltr }}</p>

<!-- For nested patient objects -->
<p>Patient: {% patient_name appointment.patient %}</p>
<p>Phone: {{ appointment.patient.phone_number|ltr }}</p>

How It Works:

1. English Language Selected:

   • {% patient_name patient %} → Returns "John Smith" (from full_name_en)
   • {{ patient.phone|ltr }} → Returns <span dir="ltr">+966501234567</span>

2. Arabic Language Selected:

   • {% patient_name patient %} → Returns "جون سميث" (from full_name_ar)
   • {{ patient.phone|ltr }} → Returns <span dir="ltr">+966501234567</span> (still LTR)

4. Benefits

1. Automatic Language Switching: Patient names automatically display in the correct language based on user's language preference
2. Consistent Phone Display: Phone numbers always display left-to-right, maintaining readability
3. Centralized Logic: All language logic is in one place (template tags), making it easy to maintain
4. Backward Compatible: Falls back to English names if Arabic names are not available
5. No Code Duplication: Single implementation used across all 85+ templates

5. Testing

To test the implementation:

1. Switch to English:

   • Navigate to any patient page
   • Verify patient names show in English
   • Verify phone numbers display left-to-right

2. Switch to Arabic:

   • Change language to Arabic in the UI
   • Navigate to the same patient page
   • Verify patient names show in Arabic (if available)
   • Verify phone numbers still display left-to-right

3. Test Locations:

   • Patient detail page
   • Patient list
   • Appointment lists
   • Clinical records (medical, nursing, OT, SLP, ABA)
   • Financial records (invoices, payments)
   • Referrals

6. Files Modified

New Files Created:

• core/templatetags/__init__.py
• core/templatetags/patient_tags.py
• update_patient_templates.py (utility script)
• test_patient_tags.py (test script)

Templates Updated (85 files):

See the output from update_patient_templates.py for the complete list.

7. Maintenance Notes

• When creating new templates that display patient names, remember to:

  1. Load the template tags: {% load patient_tags %}
  2. Use {% patient_name patient %} instead of {{ patient.full_name_en }}
  3. Use {{ patient.phone|ltr }} for phone numbers

• The template tags handle None values gracefully, returning empty strings

8. Future Enhancements

Potential improvements:

1. Add similar tags for other bilingual fields (clinic names, etc.)
2. Create a template tag for caregiver names
3. Add unit tests for the template tags
4. Consider adding a context processor to make language-aware display automatic

Conclusion

The implementation successfully makes patient names language-aware across the entire project while ensuring phone numbers always display in the correct direction. This improves the user experience for Arabic-speaking users while maintaining compatibility with English users.