Adding Translations for API Documentation Content (#400)

* created centralized doc

* adding content to views

* adding filter content

* adding unit tests

* adding translation functionality

* adding documentation

* fixing failing tests

Author: sachin-panayil

backend/app/settings.py

@@ -20,6 +20,12 @@
 
 from app.logging import sql_trace_formatter
 
+LANGUAGE_CODE = "en-us"
+
+LANGUAGES = [
+    ("en", ("English")),
+]
+
 # Build paths inside the project like this: BASE_DIR / 'subdir'.
 BASE_DIR = Path(__file__).resolve().parent.parent
 
@@ -41,6 +47,10 @@
 
 INTERNAL_APIS = config("DJANGO_ALLOWED_HOSTS").split(",")
 
+LOCALE_PATHS = [
+    os.path.join(BASE_DIR, "locale"),
+]
+
 # Application definition
 
 INSTALLED_APPS = [
@@ -73,6 +83,7 @@
     "django.middleware.security.SecurityMiddleware",
     "whitenoise.middleware.WhiteNoiseMiddleware",
     "django.contrib.sessions.middleware.SessionMiddleware",
+    "django.middleware.locale.LocaleMiddleware",
     "django.middleware.common.CommonMiddleware",
     "django.middleware.csrf.CsrfViewMiddleware",
     "django.contrib.auth.middleware.AuthenticationMiddleware",

backend/locale/README.md

@@ -0,0 +1,47 @@
+# Localization
+
+The NPD API documentation supports internationalization via Django's translation framework. All API documentation strings in `documentation_content.py` are wrapped in `gettext_lazy` so they are translation ready.
+
+Currently, only English is supported. No additional setup is required until we decide to add a new language.
+
+## Adding a New Language
+
+1. **Register the language** in `settings.py`:
+
+```python
+LANGUAGES = [
+    ("en", _("English")),
+    ("es", _("Spanish")),  # add new language here
+]
+```
+
+2. **Generate translation files**:
+
+```bash
+python manage.py makemessages -l es
+```
+
+This scans all `_()` calls and creates `locale/es/LC_MESSAGES/django.po`.
+
+3. **Translate the strings** in the generated `.po` file. Each entry has a `msgid` which is the original English string and a `msgstr` where the translation goes.
+
+4. **Compile translations**:
+
+```bash
+python manage.py compilemessages
+```
+
+This produces `.mo` binary files that Django reads at runtime.
+
+
+## File Structure
+
+```
+locale/
+└── es/
+    └── LC_MESSAGES/
+        ├── django.po    # human-editable translations
+        └── django.mo    # compiled binary (generated, do not edit)
+```
+
+**NOTE:** We should add `*.mo` to `.gitignore` and integrate `compilemessages` as part of our build/deploy process. `makemessages` must be a manual step done by the developer so it can be ready for compilation.

backend/npdfhir/documentation_content.py

@@ -1,157 +1,164 @@
+from django.utils.translation import gettext_lazy as _
+
+
 class docs:
     # Centralized namespace for all NPD API documentation content
 
     class constants:
         # Constant strings that appear throughout content building
 
-        sort_order_text = "Default sort order: "
+        sort_order_text = _("Default sort order: ")
 
     class filters:
         # Help text for filter parameters, organized by FHIR resource
 
         class practitioner:
-            name = (
+            name = _(
                 "Filter by practitioner name (first, middle, last, or full name). "
                 "Name filter accepts websearch syntax."
             )
-            gender = "Filter by practitioner gender"
-            identifier = (
+            gender = _("Filter by practitioner gender")
+            identifier = _(
                 "Filter by practitioner identifier (NPI or other). Format: value or system|value"
             )
-            type = (
+            type = _(
                 "Filter by practitioner type/taxonomy. "
                 "Practitioner type filter accepts websearch syntax."
             )
 
         class organization:
-            name = "Filter by organization name"
-            identifier = (
+            name = _("Filter by organization name")
+            identifier = _(
                 "Filter by organization identifier (NPI, EIN, or other). "
                 "Format: value or system|value"
             )
-            type = "Filter by organization type/taxonomy"
+            type = _("Filter by organization type/taxonomy")
 
         class location:
-            name = "Filter by location name"
-            near = (
+            name = _("Filter by location name")
+            near = _(
                 "Filter by distance from a point expressed as "
                 "[latitude]|[longitude]|[distance]|[units]. "
                 "If no units are provided, km is assumed."
             )
 
         class endpoint:
-            name = "Filter by endpoint name"
-            connection_type = "Filter by endpoint connection type"
-            payload_type = "Filter by endpoint payload type"
-            status = "Filter by endpoint status"
+            name = _("Filter by endpoint name")
+            connection_type = _("Filter by endpoint connection type")
+            payload_type = _("Filter by endpoint payload type")
+            status = _("Filter by endpoint status")
 
         class practitioner_role:
-            active = "Filter by active status"
-            role = "Filter by provider role code"
-            specialty = "Filter by Nucc/Snomed specialty code"
+            active = _("Filter by active status")
+            role = _("Filter by provider role code")
+            specialty = _("Filter by Nucc/Snomed specialty code")
 
         class address:
-            full = "Filter by any part of address. Address filter accepts websearch syntax."
-            city = "Filter by city name"
-            state = "Filter by state (2-letter abbreviation)"
-            postalcode = "Filter by postal code/zip code"
-            use = "Filter by address use type"
+            full = _("Filter by any part of address. Address filter accepts websearch syntax.")
+            city = _("Filter by city name")
+            state = _("Filter by state (2-letter abbreviation)")
+            postalcode = _("Filter by postal code/zip code")
+            use = _("Filter by address use type")
 
     class endpoints:
         # Descriptions for API endpoints
 
         class practitioner:
-            viewset = "ViewSet for FHIR Practitioner resources"
-            list_description = (
+            viewset = _("ViewSet for FHIR Practitioner resources")
+            list_description = _(
                 "Query a list of healthcare providers, represented as a "
                 "bundle of FHIR Practitioner resources"
             )
-            default_sort = "ascending last name, first name"
-            retrieve_description = "Query a specific provider as a FHIR Practitioner resource"
-            list_response = (
+            default_sort = _("ascending last name, first name")
+            retrieve_description = _("Query a specific provider as a FHIR Practitioner resource")
+            list_response = _(
                 "Successfully retrieved FHIR Bundle resource of FHIR Practitioner resources"
             )
-            retrieve_response = "Successfully retrieved FHIR Practitioner resource"
+            retrieve_response = _("Successfully retrieved FHIR Practitioner resource")
 
         class practitioner_role:
-            viewset = "ViewSet for FHIR PractitionerRole resources"
-            list_description = (
+            viewset = _("ViewSet for FHIR PractitionerRole resources")
+            list_description = _(
                 "Query a list of relationships between providers, healthcare "
                 "organizations, and practice locations, represented as a "
                 "bundle of FHIR PractitionerRole resources"
             )
-            default_sort = "ascending by location name"
-            retrieve_description = (
+            default_sort = _("ascending by location name")
+            retrieve_description = _(
                 "Query a specific relationship between providers, healthcare "
                 "organizations, and practice locations, represented as a "
                 "FHIR PractitionerRole resource"
             )
-            list_response = (
+            list_response = _(
                 "Successfully retrieved FHIR Bundle resource of FHIR PractitionerRole resources"
             )
-            retrieve_response = "Successfully retrieved FHIR PractitionerRole resource"
+            retrieve_response = _("Successfully retrieved FHIR PractitionerRole resource")
 
         class organization:
-            viewset = "ViewSet for FHIR Organization resources"
-            list_description = (
+            viewset = _("ViewSet for FHIR Organization resources")
+            list_description = _(
                 "Query a list of organizations, represented as a bundle "
                 "of FHIR Organization resources"
             )
-            default_sort = "ascending by organization name"
-            retrieve_description = (
+            default_sort = _("ascending by organization name")
+            retrieve_description = _(
                 "Query a specific organization, represented as a FHIR Organization resource"
             )
-            list_response = (
+            list_response = _(
                 "Successfully retrieved FHIR Bundle resource of FHIR Organization resources"
             )
-            retrieve_response = "Successfully retrieved FHIR Organization resource"
+            retrieve_response = _("Successfully retrieved FHIR Organization resource")
 
         class organization_affiliation:
-            viewset = "ViewSet for FHIR EHR Vendor to Organization relationships"
-            list_description = (
+            viewset = _("ViewSet for FHIR EHR Vendor to Organization relationships")
+            list_description = _(
                 "Query a list of EHR vendor to organization relationships, "
                 "represented as a bundle of FHIR OrganizationAffiliation "
                 "resources"
             )
-            default_sort = "ascending by organization name"
-            retrieve_description = (
+            default_sort = _("ascending by organization name")
+            retrieve_description = _(
                 "Query a specific EHR vendor to organization relationship, "
                 "represented as a FHIR OrganizationAffiliation resource"
             )
-            list_response = (
+            list_response = _(
                 "Successfully retrieved FHIR Bundle resource of "
                 "FHIR OrganizationAffiliation resources"
             )
-            retrieve_response = "Successfully retrieved FHIR OrganizationAffiliation resource"
+            retrieve_response = _("Successfully retrieved FHIR OrganizationAffiliation resource")
 
         class location:
-            viewset = "ViewSet for FHIR Location resources"
-            list_description = (
+            viewset = _("ViewSet for FHIR Location resources")
+            list_description = _(
                 "Query a list of healthcare practice locations, represented "
                 "as a bundle of FHIR Location resources"
             )
-            default_sort = "ascending by location name"
-            retrieve_description = (
+            default_sort = _("ascending by location name")
+            retrieve_description = _(
                 "Query a specific healthcare practice location as a FHIR Location resource"
             )
-            list_response = "Successfully retrieved FHIR Bundle resource of FHIR Location resources"
-            retrieve_response = "Successfully retrieved FHIR Location resource"
+            list_response = _(
+                "Successfully retrieved FHIR Bundle resource of FHIR Location resources"
+            )
+            retrieve_response = _("Successfully retrieved FHIR Location resource")
 
         class endpoint:
-            viewset = "ViewSet for FHIR Endpoint resources"
-            list_description = (
+            viewset = _("ViewSet for FHIR Endpoint resources")
+            list_description = _(
                 "Query a list of interoperability endpoints, represented "
                 "as a bundle of FHIR Endpoint resources"
             )
-            default_sort = "ascending by endpoint instance name"
-            retrieve_description = "Query a specific endpoint as a FHIR Endpoint resource"
-            list_response = "Successfully retrieved FHIR Bundle resource of FHIR Endpoint resources"
-            retrieve_response = "Successfully retrieved FHIR Endpoint resource"
+            default_sort = _("ascending by endpoint instance name")
+            retrieve_description = _("Query a specific endpoint as a FHIR Endpoint resource")
+            list_response = _(
+                "Successfully retrieved FHIR Bundle resource of FHIR Endpoint resources"
+            )
+            retrieve_response = _("Successfully retrieved FHIR Endpoint resource")
 
         class capability_statement:
-            viewset = "ViewSet for FHIR CapabilityStatement resource"
-            get_description = (
+            viewset = _("ViewSet for FHIR CapabilityStatement resource")
+            get_description = _(
                 "Query metadata about this FHIR instance, represented as "
                 "FHIR CapabilityStatement resource"
             )
-            get_response = "Successfully retrieved FHIR CapabilityStatement resource"
+            get_response = _("Successfully retrieved FHIR CapabilityStatement resource")