Global-Ready Django Framework

GEOGRAPHIC CANON.

/// LOCALE_CANONICAL_LAYER 190+ jurisdictions, dial codes, flags, timezones, languages, and public holidays. Make your Django app global-ready from day one.

EXPLORE ARCHITECTURE INSTALLATION

CANONICAL DATA FOR

JURISDICTIONS DIAL CODES FLAGS TIMEZONES HOLIDAYS LANGUAGES

The Localisation Problem

Stop rebuilding locale infrastructure for every project. One canonical source of truth for geographic data.

Scattered Data

Country lists hardcoded in templates. Timezone logic scattered across views. Dial codes copy-pasted from Stack Overflow. Every project reinvents the wheel.

# ❌ Ad-hoc locale handling
COUNTRY_CHOICES = [ ('US', 'United States'), ('UK', 'United Kingdom'), # ... copy-paste 190 more? # ⚠️ Which ISO standard? # ⚠️ Are they translatable? # ⚠️ What about dial codes? ]

GeoCanon

One import. Canonical, typed, translatable data for 190+ jurisdictions. Forms, middleware, and settings included.

# ✅ Canonical locale data
from geo_canon import ( get_jurisdiction_choices, get_dial_code, get_flag_css_class, get_current_local_time, ) # 190+ jurisdictions, typed & translatable # Dial codes, flags, timezones — all linked

SEVEN MODULES.

Everything a Django application needs to serve a global user base, in one coherent package.

Jurisdictions

190+ countries with translatable names, form fields, and context-switching middleware.

  • JurisdictionChoiceField for forms
  • Session-based middleware
  • Validation helpers

Dial Codes

International dial codes for 150+ countries with phone number validation patterns.

  • Country-to-code mapping
  • Regex phone validation
  • Django form choices

Flags

Country-to-ISO-3166 CSS class mapping compatible with the flag-icons library.

  • 190+ flag CSS classes
  • QuerySet annotation helper
  • Reverse ISO lookup

Timezones

200+ jurisdiction-to-IANA timezone mappings with aware datetime utilities.

  • zoneinfo + pytz fallback
  • Settings-level overrides
  • get_current_local_time()

Public Holidays

Holiday detection for 140+ countries powered by the open-source holidays library.

  • is_public_holiday() check
  • Full year holiday listing
  • Optional dependency

Languages

75+ language choices with jurisdiction-to-default-language mapping.

  • Django LANGUAGE_CODE compatible
  • Jurisdiction auto-detection
  • Sorted form choices

Designed for Global Scale

Stop copy-pasting country lists. GeoCanon provides production-grade, typed, translatable geographic data with Django-native integration.

Rich Exceptions

Every error includes a hint and a documentation link. No more cryptic stack traces.

Pydantic Settings

Type-safe configuration with validation. Works with or without Pydantic installed.

PEP 561 Typed

Full py.typed support for MyPy and VS Code autocompletion out of the box.

views.py
from geo_canon import (
    get_current_local_time,
    get_flag_css_class,
    is_public_holiday,
)

def dashboard(request):
    jurisdiction = request.jurisdiction
    now = get_current_local_time(jurisdiction)
    flag = get_flag_css_class(jurisdiction)
    holiday = is_public_holiday(jurisdiction)
    # All data — one canonical source

INTEGRATION

1 Install the package

$ pip install geocanon[all]

2 Configure in settings.py 

# settings.py

GEOCANON = {
    "default_jurisdiction": "United Kingdom",
    "default_language": "en",
    "enable_form_widgets": True,
}

MIDDLEWARE = [
    # ...
    "geo_canon.jurisdictions.middleware.JurisdictionMiddleware",
]

3 Use anywhere in your app 

from geo_canon.jurisdictions.forms import JurisdictionContextSwitchForm
from geo_canon.timezones import get_current_local_time
from geo_canon.holidays import is_public_holiday
from geo_canon.flags import get_flag_css_class

# request.jurisdiction is set automatically by the middleware
local_time = get_current_local_time(request.jurisdiction)
flag_class = get_flag_css_class(request.jurisdiction)

Global operations playbook

Design once, localize everywhere

GeoCanon helps product, legal, and engineering teams move at the same speed by centralizing jurisdiction data into one versioned source. Teams avoid drift between forms, billing, reporting, and support tooling.

Product teams

Ship locale-aware UX defaults for language, region formatting, and holidays without hardcoding market-specific branches.

Operations teams

Coordinate support windows and cutoff times from local timezone truth instead of manually maintained spreadsheets.

Compliance teams

Track jurisdiction-level policy requirements with consistent naming and stable IDs for downstream audits.

Common implementation outcomes

  • • One canonical jurisdiction object shared across apps and services.
  • • Fewer production regressions from stale localization constants.
  • • Faster expansion to new countries with predictable onboarding checklists.
  • • Cleaner analytics slices by geography with validated identifiers.