Internationalization and Time Zones

Think of it as

The useful split is between what is *stored* and what is *shown*, and each pair of settings sits on one side of it. With `USE_TZ` on, every datetime you save goes to the database in UTC — one unambiguous instant, the same value regardless of who wrote it. `TIME_ZONE` then governs how that instant is rendered when nothing more specific applies, which is why calling it "the project timezone" misleads people into thinking it changes storage. It does not. The same shape holds for language: the strings in your code are one canonical language, and `LANGUAGE_CODE` is only the fallback used for rendering when a request has expressed no preference of its own. Requests almost always do express one. With `LocaleMiddleware` installed, Django resolves the active language per request in a documented order — a language prefix in the URL, then a cookie, then the `Accept-Language` header, then `LANGUAGE_CODE` — and the result lands on `request.LANGUAGE_CODE`. The equivalent for time has no such default: Django will not guess a user's timezone, because a browser does not send one in a header. You have to obtain it, store it against the user or the session, and call `timezone.activate()` per request. Until you do, every timestamp on the page renders in `TIME_ZONE`, which is correct for exactly the subset of your users who happen to live there. The two settings that are usually wrong in an existing project are these last two: `USE_TZ` turned off years ago by someone who found aware datetimes annoying, and a `TIME_ZONE` set to the founder's city and quietly treated as though it were storage.

Think of it as

Everything here follows from one timing question: is this string produced now, or reused for the lifetime of the process? A view body runs per request, and by then `LocaleMiddleware` has already activated a language — so `gettext` gets the right answer and returns a plain string. A model class body runs once, at import, long before any request exists. If you use `gettext` there, the string is translated exactly once into whichever language happened to be active during startup, and every user afterwards sees that language regardless of their own. This is the failure the documentation is describing when it says lazy translation is essential in code paths executed at module load time. `gettext_lazy` avoids it by not translating at all: it hands back a lazy object that carries the original string and resolves against the active language at the moment something asks it for text — which is during rendering, per request, per user. The cost of that cleverness is that a lazy object is not a `str`, and the places where that leaks are worth memorising rather than rediscovering. `str.format()` does not work when the format string or any argument is a lazy object, so `format_lazy` exists for that case. Concatenating lazily with `+` is the same trap. And serialising one — into JSON, into a cache, into a task argument — either raises or silently stores something you did not intend, because the whole point of the object is that it has not decided what it says yet. The workflow around the markers is deliberately dull: `makemessages` scans your source for the calls and writes `.po` files under `locale/<lang>/LC_MESSAGES/`, translators edit those, `compilemessages` turns them into the binary `.mo` files gettext actually reads. Two consequences follow from `makemessages` being a *scanner*. It can only find literal strings inside the marker calls, so a variable passed to `_()` extracts nothing. And because `.mo` is what gets read at runtime, a deploy that ships `.po` files without compiling them shows the original language with no error at all.

Think of it as

Hold two different things apart: an *instant* and a *reading*. An instant is a point on the universal timeline, and UTC names it unambiguously. A reading is what a clock on a particular wall says, and it is a rendering of an instant through a timezone — a lossy one, because the same reading can correspond to more than one instant, or to none. That is not a rare edge case, it happens twice a year everywhere daylight saving is observed. When clocks go back, one hour of readings repeats; when they go forward, one hour of readings never occurs. Django's design follows directly: store the instant, render the reading. With `USE_TZ` on, `timezone.now()` returns an aware datetime and the database column holds UTC, so ordering, subtraction and comparison all work because every row is on the same timeline. Rendering happens per request against the activated zone, in templates automatically and in Python through `localtime()`. The mistakes cluster at the boundary where a reading enters or leaves the system. Input from a form or an API is a reading — the user typed a wall-clock time — so it must be attached to the zone it was written in before it becomes an instant. Output to a person is a reading, so it must be converted. Output to *another machine* is an instant, and should stay ISO-8601 with an offset. Between those boundaries, resist the urge to hold local times in variables; the moment a naive value exists in your code, some later line will compare it to an aware one and raise, or worse, will not. Two operations deserve specific care. Arithmetic across a DST boundary is not what people expect: adding `timedelta(days=1)` to an aware datetime adds exactly 24 hours of elapsed time, which lands on a different wall-clock reading on the two days a year the day is 23 or 25 hours long. And grouping by day for a report is a *local* question, so truncating in UTC quietly assigns some evening rows to the wrong day for readers in other zones.