l10n documentation

A library and CLI for translating Python applications and libraries.

Our main design principle is “Simple things should be simple, complex things should be possible”. We streamline the workflow that fits 95% of the projects and allow to configure every small detail to make it possible to fit the remaining 5%. Think about l10n as a high-level and friendly library comparing to low-level and less friendly locale, gettext, and babel.


  • Simple. We stripped away all unnecessary steps and concepts. All that’s left is what is actually relevant for Python.

  • Type-safe. All other tools match translation.

  • Explicit. No global state, no variable injection. You know exactly what gets translated and to what language.

  • Zero-dependency runtime. There are a few small dependencies for CLI but they get installed only on your dev environment. On the production goes only one small library, l10n itself.

  • Pure Python. You can use it with PyPy, Numba, and any other interpreter.

  • Zero configuration. The tool knows about the modern Python packaging and automatically discovers the project structure, name, version, and all other relevant metadata.

  • Well documented. We make sure that you can pick up the tool without any prior knowledge of the topic.

  • Compatible with other tools. We use *.po and *.mo files that are compatible with gettext toolchain and all other translation tools.

  • Self-sufficient, no other tools required.

  • Asyncio-compatible and race-condition-free.

  • Fast. All teanslations on the production are compiled into a small and fast binary format.

  • Small. We don’t include any generated data into the library distribution. Just a little of Python code.

  • Lazy. Any data is loaded only when you need it.

  • Can be used in libraries. The compiled translations are automatically placed next to your Python code and discovered at runtime.

  • Versatile. Most of the libraries in the wild are focused on web applications. This library fits any Python project.


  • TL;DR is a guide for impatient that in 30 seconds shows you how to use l10n.

  • Getting Started walks you through the process of creating and translating your first Python project.

  • Advanced usage goes deeper into details and going beyond translating simple messages.

  • Beyond l10n links some helpful tools and resources to find your way around of translating things.

  • What we stripped away tells the secret of l10n’s simplicity.

Source code is available on GitHub: github.com/orsinium-labs/l10n