fastapi-locale 0.1.0rc1__tar.gz

fastapi_locale-0.1.0rc1/.gitignore

@@ -0,0 +1,40 @@
+# Python
+__pycache__/
+*.py[cod]
+
+# Packaging
+build/
+dist/
+*.egg-info/
+
+# Environments
+.venv/
+.env
+.env.*
+
+# Tests and tools
+.pytest_cache/
+.coverage
+.coverage.*
+coverage.xml
+htmlcov/
+.hypothesis/
+.benchmarks/
+.mypy_cache/
+.ruff_cache/
+.import_linter_cache/
+
+# Compiled catalogs are build output; .po files are the source
+*.mo
+
+# Documentation build
+site/
+
+# Editors and OS
+.vscode/
+.idea/
+*.swp
+.DS_Store
+
+# Local scratch files and visual aids, never committed
+.tmp/

fastapi_locale-0.1.0rc1/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes are listed here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the project uses
+[semantic versioning](https://semver.org).
+
+## [Unreleased]
+
+## [0.1.0rc1] - 2026-09-28
+
+First release candidate. Installs only with `pip install --pre fastapi-locale` or an exact version.
+
+### Added
+
+- Per-request locale from query parameter, cookie and `Accept-Language`, with RFC 4647 matching and
+  `Content-Language` and `Vary` response headers.
+- gettext, ngettext, pgettext, npgettext and their domain variants, with named placeholders.
+- `LazyText` for translatable text in Pydantic models, response models and `HTTPException.detail`.
+- Localized 422 validation errors for every Pydantic error type, with built-in German, Spanish, French,
+  Hindi and Portuguese (Brazil) translations.
+- `set_locale()` to apply a signed-in user's language for the rest of a request.
+- `LocaleDep` and `TranslatorDep` dependencies, `use_locale()`, and test helpers.
+- `fastapi-locale` command: extract, init, update, compile and check.
+- Localized OpenAPI schema: Swagger UI and ReDoc follow the request locale, with built-in
+  translations of FastAPI's own schema text. Turn off with `localize_openapi=False`.

fastapi_locale-0.1.0rc1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 fastapi-locale contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fastapi_locale-0.1.0rc1/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.5
+Name: fastapi-locale
+Version: 0.1.0rc1
+Summary: Internationalization for FastAPI: gettext catalogs, per-request locales, lazy text and localized validation errors.
+Project-URL: Homepage, https://github.com/fastapi-extensions/fastapi-locale
+Project-URL: Documentation, https://fastapi-locale.readthedocs.io
+Project-URL: Repository, https://github.com/fastapi-extensions/fastapi-locale
+Project-URL: Bug Tracker, https://github.com/fastapi-extensions/fastapi-locale/issues
+Project-URL: Changelog, https://github.com/fastapi-extensions/fastapi-locale/blob/main/CHANGELOG.md
+Author: fastapi-locale contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: babel,fastapi,gettext,i18n,internationalization,l10n,localization,pydantic
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Framework :: Pydantic :: 2
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Internationalization
+Classifier: Topic :: Software Development :: Localization
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: babel>=2.12.0
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: pydantic>=2.7.0
+Description-Content-Type: text/markdown
+
+# fastapi-locale
+
+Internationalization for [FastAPI](https://fastapi.tiangolo.com), built on standard gettext catalogs.
+
+- Picks a locale for every request from a query parameter, cookie or `Accept-Language`, with RFC 4647
+  matching and correct `Content-Language` and `Vary` headers.
+- Returns FastAPI's 422 validation errors in the client's language, with correct plural forms.
+- Lazy text that works in Pydantic models, response models and `HTTPException.detail`.
+- Dependency injection first: `LocaleDep` and `TranslatorDep`, replaceable in tests.
+- Lets a dependency switch to the signed-in user's saved language for the rest of the request.
+- A command line tool to extract, update, compile and check catalogs in CI.
+
+> **Status:** in development, not yet released. The design is in [docs/](docs/project-documents.md).
+
+## Quick start
+
+```python
+from fastapi import FastAPI, HTTPException
+
+from fastapi_locale import LocaleConfig, Localization, TranslatorDep, gettext_lazy
+
+i18n = Localization(
+    LocaleConfig(default_locale="en", supported_locales=["en", "hi", "de"], catalog_dirs=["locales"])
+)
+app = FastAPI()
+i18n.install(app)
+
+NOT_FOUND = gettext_lazy("Item not found")
+
+
+@app.get("/items/{item_id}")
+def read_item(item_id: int, tr: TranslatorDep) -> dict[str, str]:
+    if item_id != 1:
+        raise HTTPException(status_code=404, detail=NOT_FOUND)
+    return {"name": tr.gettext("Sample item")}
+```
+
+A request with `Accept-Language: de` now gets German text, German validation errors and
+`Content-Language: de`.
+
+## Translation workflow
+
+```sh
+fastapi-locale extract          # scan the code, write locales/messages.pot
+fastapi-locale init --locale hi # start a new language
+fastapi-locale update           # merge new messages into every .po file
+fastapi-locale compile          # build .mo files
+fastapi-locale check            # fail CI when catalogs are stale or broken
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). The engineering documents (requirements, models, architecture,
+decisions and test plan) are in [docs/](docs/project-documents.md).
+
+## License
+
+MIT

fastapi_locale-0.1.0rc1/README.md

@@ -0,0 +1,58 @@
+# fastapi-locale
+
+Internationalization for [FastAPI](https://fastapi.tiangolo.com), built on standard gettext catalogs.
+
+- Picks a locale for every request from a query parameter, cookie or `Accept-Language`, with RFC 4647
+  matching and correct `Content-Language` and `Vary` headers.
+- Returns FastAPI's 422 validation errors in the client's language, with correct plural forms.
+- Lazy text that works in Pydantic models, response models and `HTTPException.detail`.
+- Dependency injection first: `LocaleDep` and `TranslatorDep`, replaceable in tests.
+- Lets a dependency switch to the signed-in user's saved language for the rest of the request.
+- A command line tool to extract, update, compile and check catalogs in CI.
+
+> **Status:** in development, not yet released. The design is in [docs/](docs/project-documents.md).
+
+## Quick start
+
+```python
+from fastapi import FastAPI, HTTPException
+
+from fastapi_locale import LocaleConfig, Localization, TranslatorDep, gettext_lazy
+
+i18n = Localization(
+    LocaleConfig(default_locale="en", supported_locales=["en", "hi", "de"], catalog_dirs=["locales"])
+)
+app = FastAPI()
+i18n.install(app)
+
+NOT_FOUND = gettext_lazy("Item not found")
+
+
+@app.get("/items/{item_id}")
+def read_item(item_id: int, tr: TranslatorDep) -> dict[str, str]:
+    if item_id != 1:
+        raise HTTPException(status_code=404, detail=NOT_FOUND)
+    return {"name": tr.gettext("Sample item")}
+```
+
+A request with `Accept-Language: de` now gets German text, German validation errors and
+`Content-Language: de`.
+
+## Translation workflow
+
+```sh
+fastapi-locale extract          # scan the code, write locales/messages.pot
+fastapi-locale init --locale hi # start a new language
+fastapi-locale update           # merge new messages into every .po file
+fastapi-locale compile          # build .mo files
+fastapi-locale check            # fail CI when catalogs are stale or broken
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). The engineering documents (requirements, models, architecture,
+decisions and test plan) are in [docs/](docs/project-documents.md).
+
+## License
+
+MIT

fastapi_locale-0.1.0rc1/docs/about/changelog.md

@@ -0,0 +1,2 @@
+<!-- markdownlint-disable-file MD041 -->
+--8<-- "CHANGELOG.md"

fastapi_locale-0.1.0rc1/docs/about/contributing.md

@@ -0,0 +1,2 @@
+<!-- markdownlint-disable-file MD041 -->
+--8<-- "CONTRIBUTING.md"

fastapi_locale-0.1.0rc1/docs/about/license.md

@@ -0,0 +1,5 @@
+# License
+
+```text
+--8<-- "LICENSE"
+```

fastapi_locale-0.1.0rc1/docs/about/security.md

@@ -0,0 +1,2 @@
+<!-- markdownlint-disable-file MD041 -->
+--8<-- "SECURITY.md"

fastapi_locale-0.1.0rc1/docs/adr/0001-record-architecture-decisions.md

@@ -0,0 +1,23 @@
+# ADR-0001: Record architecture decisions
+
+- Status: Accepted
+- Date: 2026-09-26
+
+## Context
+
+The library will be maintained in the open, and contributors will ask why it works the way it does. Those
+answers should not live only in issue threads or in one person's head.
+
+## Decision
+
+Record each significant decision as a short Markdown file in `docs/adr/`, numbered in order. Each record
+has these sections: Status, Date, Context, Options considered, Decision, Consequences, and Related
+requirements where they apply.
+
+Status is one of Proposed, Accepted, Superseded by ADR-NNNN, or Rejected. An accepted record is not edited
+except to change its status; a new record replaces it.
+
+## Consequences
+
+- Reviewers can check a pull request against the recorded decisions.
+- Changing a decision takes a new record, which makes the change and its reasons visible.

fastapi_locale-0.1.0rc1/docs/adr/0002-gettext-catalogs-through-babel.md

@@ -0,0 +1,39 @@
+# ADR-0002: Use GNU gettext catalogs loaded through Babel
+
+- Status: Accepted
+- Accepted: 2026-09-28
+- Date: 2026-09-26
+
+## Context
+
+Translations need a storage format that translators already know, that handles plural forms correctly for
+every language, and that has tooling for extracting messages from Python code.
+
+## Options considered
+
+1. **GNU gettext (`.po` / `.mo`) read with Babel.** The standard in Python (Django, Flask-Babel, CPython
+   itself). Supported by Poedit, Weblate, Crowdin, Transifex and Lokalise. Babel adds CLDR plural rules,
+   message extraction and compilation.
+2. **gettext through the standard library only.** No extra dependency, but no extraction tooling, no CLDR
+   data and no locale formatting later.
+3. **JSON or YAML catalogs.** Easy to read, but every project invents its own plural and context
+   conventions, and the translation tools support them unevenly.
+4. **Fluent (Project Fluent).** Expressive, but little adoption in the Python web world and a heavier
+   runtime.
+
+## Decision
+
+Use option 1. Catalogs are `.po` files in the repository, compiled to `.mo` for runtime. Babel is a
+runtime dependency, used for loading `.mo` files and plural rules, and the CLI builds on Babel's
+extraction and compilation.
+
+## Consequences
+
+- Translators can use the tools they already have (C-01).
+- Plural rules come from CLDR through each catalog's `Plural-Forms` header (TRN-02).
+- Babel becomes a required dependency. It is mature and widely used, so the risk is low.
+- JSON catalogs can still be added later behind the same catalog store interface, as the SRS notes.
+
+## Related requirements
+
+C-01, C-04, CAT-01, CAT-02, TRN-02, CLI-01, CLI-02

fastapi_locale-0.1.0rc1/docs/adr/0003-request-locale-in-a-context-variable.md

@@ -0,0 +1,53 @@
+# ADR-0003: Hold the request locale in a context variable with a per-request holder
+
+- Status: Accepted
+- Accepted: 2026-09-28
+- Date: 2026-09-26
+
+## Context
+
+Code deep inside a request (a service function, a Pydantic serializer, a background task) needs to know
+the request's locale without it being passed through every call. FastAPI runs async code on the event
+loop and sync code in a thread pool, and many requests run at the same time.
+
+Experiments with FastAPI 0.141.1 showed:
+
+- A value set in a `ContextVar` by pure ASGI middleware is visible in sync dependencies, the endpoint,
+  exception handlers and background tasks.
+- A value set with `ContextVar.set()` inside a dependency or a sync endpoint is **not** visible to
+  exception handlers or response serialization, because those run in a different context copy.
+
+## Options considered
+
+1. **Thread-local or global state.** Wrong under asyncio: concurrent requests on one thread overwrite
+   each other. Rejected.
+2. **`request.state` only.** Safe, but code without the `Request` object cannot reach it, which rules out
+   lazy text and plain `gettext()` calls.
+3. **`ContextVar` holding the locale value.** Safe and reachable everywhere, but changes made in a
+   dependency are lost, as the experiment shows.
+4. **`ContextVar` holding a small mutable per-request object (`RequestLocale`).** The middleware creates
+   one object per request and sets it once. Later changes modify the object, so every context copy that
+   refers to it sees them.
+
+## Decision
+
+Use option 4. The middleware creates a `RequestLocale`, sets it in a module-level `ContextVar` and resets
+the variable with its token when the request ends. `set_locale()` changes the object in place.
+`use_locale()` sets a new, separate object for the length of a block and restores the previous one with its
+token.
+
+The `RequestLocale` is also stored in the ASGI scope so code that has the `Request` can reach it
+explicitly.
+
+## Consequences
+
+- Correct under asyncio and in the thread pool (C-02, NFR-07).
+- Changes made by the user's dependency reach the 422 handler and the `Content-Language` header
+  (see ADR-0004).
+- Tasks started with `asyncio.create_task` inside a request share the object. A change by one task is seen
+  by the others. This is the intended behaviour for one request and is documented.
+- Several applications in one process each create their own holders, so they do not interfere (DI-04).
+
+## Related requirements
+
+C-02, LOC-01, LOC-13, LOC-14, LOC-15, TRN-05, TRN-06, DI-04, NFR-07

fastapi_locale-0.1.0rc1/docs/adr/0004-middleware-resolves-dependencies-refine.md

@@ -0,0 +1,51 @@
+# ADR-0004: Resolve the locale in middleware and let dependencies refine it
+
+- Status: Accepted
+- Accepted: 2026-09-28
+- Date: 2026-09-26
+
+## Context
+
+FastAPI developers expect dependency injection, so resolving the locale in a dependency looks natural.
+But a locale must also be available where no route dependency runs: the 422 validation handler, HTTP
+exception handlers, and the response headers.
+
+Many applications also store a preferred language on the user. The user is usually loaded in an auth
+dependency, which runs after any middleware. This was open issue OI-05 in the SRS.
+
+Experiments with FastAPI 0.141.1 showed:
+
+- A locale set only in an app-level dependency (as fastapi-i18n does) is missing in the 422 handler.
+- FastAPI runs a route's sub-dependencies before it validates the endpoint's own body and parameters. A
+  `current_user` dependency that changes the per-request holder (ADR-0003) is therefore seen by the 422
+  handler when the body is invalid, and by the middleware when it writes `Content-Language`.
+
+## Options considered
+
+1. **Dependency only.** Idiomatic, but 422 errors and exception handlers would ignore the locale. Rejected.
+2. **Middleware only.** Always available, but middleware cannot use the user that a dependency loads.
+3. **Middleware resolves, dependencies may refine.** The middleware resolves from the request (query,
+   cookie, header). An application dependency may call `set_locale()` to replace it for the rest of the
+   request.
+4. **The 422 handler calls an async user hook** to look up the user's language. Duplicates the
+   application's auth logic inside an error handler, and runs it twice per request.
+
+## Decision
+
+Use option 3. `LocaleMiddleware`, a pure ASGI middleware (not `BaseHTTPMiddleware`), resolves the locale
+before routing. Dependencies read it through `LocaleDep` and `TranslatorDep` and can change it with
+`set_locale()`.
+
+## Consequences
+
+- Localized 422 errors work with no extra setup, and they follow the user's language when the
+  application sets it in a dependency.
+- Known limit: if the user dependency's own parameters fail validation (for example a malformed
+  `Authorization` header parameter), that dependency does not run and the response uses the locale from the
+  request. The user guide will state this.
+- WebSocket connections get the same resolution (LOC-12).
+- Pure ASGI middleware avoids the known context and streaming problems of `BaseHTTPMiddleware`.
+
+## Related requirements
+
+LOC-01, LOC-10, LOC-11, LOC-12, LOC-13, ERR-01, DI-02, DI-03

fastapi_locale-0.1.0rc1/docs/adr/0005-lazy-text-type.md

@@ -0,0 +1,56 @@
+# ADR-0005: Lazy text as a dedicated Pydantic-aware type
+
+- Status: Accepted
+- Accepted: 2026-09-28
+- Date: 2026-09-26
+
+## Context
+
+Text defined at import time (default field values, shared error messages) must be translated later, in
+the locale of the request that sends it. Django calls this `gettext_lazy`.
+
+Experiments with FastAPI 0.141.1 and Pydantic 2.13.5 (see [Existing libraries](../research/existing-libraries.md),
+section 6) showed that Babel's `LazyProxy`, which starlette-babel and starlette-i18n use, fails as
+`HTTPException.detail`, in a response model, inside a returned dict, and in OpenAPI generation.
+
+## Options considered
+
+1. **Babel `LazyProxy`.** Fails in every FastAPI path tested. Rejected.
+2. **A `str` subclass** holding the msgid and overriding `__str__`. JSON encoders read the underlying
+   string, so `json.dumps` writes the msgid, untranslated. Rejected.
+3. **A dedicated class with Pydantic core schema hooks.** Serializes through a plain serializer that calls
+   `str()`, which translates in the active locale. Tested: works as a model field typed with the class, and
+   shows in OpenAPI as `{"type": "string"}`.
+4. **No lazy text**; translate eagerly everywhere. Simple, but import-time text cannot be localized.
+
+## Decision
+
+Use option 3, a final class `LazyText`:
+
+- Created by `gettext_lazy`, `ngettext_lazy`, `pgettext_lazy` and `npgettext_lazy`.
+- `str()` and `format()` translate in the active locale.
+- Pydantic validation accepts `LazyText` or `str`; JSON serialization always produces a string. Python-mode
+  `model_dump()` keeps the `LazyText`, so it can be rendered later.
+- JSON schema is `{"type": "string"}`.
+- Registered in `fastapi.encoders.ENCODERS_BY_TYPE` so `jsonable_encoder` renders it.
+- Carries a `__pydantic_serializer__`, so Pydantic also renders it where the declared type is `Any` or
+  `object`. FastAPI 0.141 serializes a route annotated `-> dict[str, object]` with Pydantic directly,
+  without `jsonable_encoder`, which an integration test found.
+- The library's HTTP exception handler renders `detail` through `jsonable_encoder`, because FastAPI's
+  default handler passes `detail` straight to `json.dumps`.
+- Equal when message, plural, context, domain and parameters are equal; hash on message, plural, context
+  and domain. Not equal to a plain `str`, because that comparison would depend on the active locale.
+- Supports pickling, so it can be passed to task queues.
+
+## Consequences
+
+- Works in response models, `HTTPException.detail` and plain dict responses (LZY-01 to LZY-05).
+- Model fields that hold lazy text must be typed `LazyText`, not `str`. Pydantic's error makes the mistake
+  obvious, and the user guide covers it.
+- `ENCODERS_BY_TYPE` is not documented FastAPI API. A test fails if FastAPI changes it, so the break is
+  caught in CI before a release.
+- Lazy text in OpenAPI metadata is handled separately (ADR-0009).
+
+## Related requirements
+
+LZY-01 to LZY-06, ERR-09

fastapi_locale-0.1.0rc1/docs/adr/0006-validation-messages-keyed-on-error-type.md

@@ -0,0 +1,51 @@
+# ADR-0006: Key validation messages on the Pydantic error type
+
+- Status: Accepted
+- Accepted: 2026-09-28
+- Date: 2026-09-26
+
+## Context
+
+FastAPI's 422 responses carry Pydantic's English `msg`. pydantic-core 2.46.5 defines 104 error types; 47
+have values in `ctx` such as `gt` or `min_length`. Some English messages build plurals inside `ctx`
+(`string_too_short` uses `{expected_plural}`), which is wrong for most other languages.
+
+pydantic-i18n, the only existing package in this area, matches the rendered English `msg` with a regular
+expression. That breaks silently when Pydantic changes its wording.
+
+## Options considered
+
+1. **Match the English `msg` text.** Fragile across Pydantic releases. Rejected.
+2. **Use Pydantic's own templates as msgids.** Ties catalogs to Pydantic's wording, which changes, and
+   keeps the English plural logic.
+3. **Library-owned templates keyed on `type`.** The library keeps one English template per error type,
+   with named placeholders that match `ctx` keys, and uses the type as the gettext message context.
+
+## Decision
+
+Use option 3.
+
+- Templates live in the library's own gettext domain, `fastapi_locale`, with `msgctxt` set to the error
+  type.
+- Types whose message depends on a number have a plural template and name the `ctx` key that picks the
+  form (for example `min_length`). English-only `ctx` keys such as `expected_plural` are ignored.
+- The built-in catalog directory is loaded first. An application overrides any message by shipping its own
+  `fastapi_locale` catalog in its catalog directories, because later directories win (CAT-04).
+- An error type with no template keeps Pydantic's `msg`.
+- For `value_error` and `assertion_error`, only the fixed prefix is translated. The rest of the message is
+  what the application raised, which it can translate with `gettext()` because validation runs inside the
+  request.
+
+## Consequences
+
+- Catalogs no longer depend on Pydantic's wording (A-02).
+- Plurals follow the target language's rules (ERR-04).
+- The library must follow new error types in pydantic-core. A test lists all error types of the installed
+  pydantic-core and fails when one has no template (NFR-09). It uses `list_all_errors`, which is not public
+  Pydantic API, so it runs only in the test suite.
+- Known limit: some `ctx` values are already English, for example `literal_error` renders `expected` as
+  `'a' or 'b'`. Those values are passed through as they are.
+
+## Related requirements
+
+ERR-01 to ERR-08, NFR-09

fastapi_locale-0.1.0rc1/docs/adr/0007-named-placeholder-formatting.md

@@ -0,0 +1,42 @@
+# ADR-0007: Named placeholder formatting instead of str.format
+
+- Status: Accepted
+- Accepted: 2026-09-28
+- Date: 2026-09-26
+
+## Context
+
+Translated messages contain values such as a name or a count. Translators must be able to move them,
+because word order differs between languages. Catalogs are often edited by outside contributors, so a
+translated string must not be able to run code or read arbitrary data.
+
+## Options considered
+
+1. **`str.format(**params)`.** A translated string like `{user.__class__}` or `{items[0]}` can read
+   attributes and items of the arguments. Rejected for security (NFR-05).
+2. **`%` formatting (`%(name)s`).** Safe from attribute access, but a translation with a missing key raises
+   `KeyError`, and the `%` syntax is easy to break when editing.
+3. **Own substitution of `{name}` only.** A small regular expression replaces `{identifier}` with the
+   string form of the named value. `{{` and `}}` produce literal braces. Anything else is left as written.
+
+## Decision
+
+Use option 3. The same syntax is used for application messages and validation error templates, and it
+matches the `{gt}` style of Pydantic's `ctx` keys.
+
+If a translation names a placeholder that has no value, the placeholder is left as written and a warning
+is logged once per message and locale. The request never fails because of it (NFR-06).
+
+`fastapi-locale check` reports translations whose placeholders differ from the msgid, so these mistakes
+are caught in CI before they reach production.
+
+## Consequences
+
+- Translators can reorder values freely (TRN-03).
+- Translated strings cannot read attributes or items.
+- Format specifications such as `{price:.2f}` are not supported. Numbers that need locale formatting will
+  use the formatting helpers planned in FMT-02.
+
+## Related requirements
+
+TRN-03, NFR-05, NFR-06, CLI-04

fastapi_locale-0.1.0rc1/docs/adr/0008-load-catalogs-at-setup.md

@@ -0,0 +1,37 @@
+# ADR-0008: Load catalogs when the application is set up
+
+- Status: Accepted
+- Accepted: 2026-09-28
+- Date: 2026-09-26
+
+## Context
+
+Catalogs must be loaded before the first request, and no file access may happen while a request is being
+handled (C-03). The first draft of the SRS said "at startup (lifespan)".
+
+## Options considered
+
+1. **In the ASGI lifespan startup event.** Fits the idea of startup, but FastAPI applications set their own
+   `lifespan`, and combining two is awkward. Starlette's `TestClient` also skips lifespan unless it is used
+   as a context manager, so tests would see unloaded catalogs.
+2. **On the first request.** Adds latency to that request and does file access during request handling.
+   Rejected.
+3. **When `Localization` is created.** Catalogs load when the application module builds its
+   `Localization(config)`, before the server accepts connections.
+
+## Decision
+
+Use option 3. Loading is fast (it reads compiled `.mo` files), and a failure raises `CatalogLoadError` at
+import time, so a broken deployment never starts. The SRS requirement CAT-03 is worded to match: catalogs
+are loaded during application setup, before the first request.
+
+## Consequences
+
+- Works the same with or without lifespan, in tests and in production.
+- Errors appear at import, which is where developers look first.
+- Importing the application module reads files. This is the same as most configuration loading and is
+  documented.
+
+## Related requirements
+
+C-03, CAT-03, CAT-05