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
