Installation — fastkit-i18n

Requirements

Python 3.10+

Minimum supported version

No hard dependencies

The core package installs nothing extra — SQLAlchemy is only needed for TranslatableMixin

Any ASGI app (optional)

FastAPI, Starlette, or Litestar — only needed if you use LocaleMiddleware

Install

If you don't have uv installed yet:

bash

curl -LsSf https://astral.sh/uv/install.sh | sh

bash

uv add fastkit-i18n

bash

pip install fastkit-i18n

bash

poetry add fastkit-i18n

This installs _(), TranslationManager, and LocaleMiddleware — ready to use, no additional steps needed.

Optional Dependencies

TranslatableMixin — translatable fields on SQLAlchemy/SQLModel models — needs SQLAlchemy. Everything else works without it:

TranslatableMixin

optional

bash

uv add "fastkit-i18n[sqlalchemy]"

bash

pip install "fastkit-i18n[sqlalchemy]"

Installs sqlalchemy>=2.0 — needed for TranslatableMixin. Works with plain SQLAlchemy declarative models and SQLModel table models alike.

What needs the extra?

Feature	Extra needed?	Installs
`_()` / `TranslationManager`	✓ Included — pure Python, no dependencies
`LocaleMiddleware`	✓ Included — pure ASGI, no dependencies
`TranslatableMixin`	`[sqlalchemy]`	`sqlalchemy>=2.0`

Importing fastkit_i18n — or using _()/LocaleMiddleware — never requires SQLAlchemy. It's only imported the moment you actually access TranslatableMixin, and you'll get a clear error telling you to install the extra if it's missing.

Verify Installation

Confirm fastkit-i18n is installed correctly:

bash

python -c "from fastkit_i18n import _; print(_('hello'))"
# hello

Or check the installed version:

bash

pip show fastkit-i18n

If you installed the [sqlalchemy] extra, verify TranslatableMixin loads:

bash

python -c "from fastkit_i18n import TranslatableMixin; print('TranslatableMixin OK')"

What do you need?

Not sure where to start? Here's a quick guide based on what you're building:

Just centralized strings

Use _() on its own — no framework, no database, no extras. Works in scripts, CLIs, or any Python project.

bash

pip install fastkit-i18n   # _() works out of the box

Detect locale automatically per request

Add LocaleMiddleware to any FastAPI/Starlette/Litestar app. Still no extra install needed.

bash

pip install fastkit-i18n   # LocaleMiddleware works out of the box

Translatable database content

Use TranslatableMixin on your SQLAlchemy or SQLModel models — requires the [sqlalchemy] extra.

bash

pip install "fastkit-i18n[sqlalchemy]"

All three pieces share the same locale context, so you can start with just _() and add LocaleMiddleware or TranslatableMixin later — nothing to rewire.

Next: Quick Start