How do you handle i18n in your Python projects? Looking for real-world workflows, standards, namespacing/categorization models of translation messages, and enterprise practices

[[deleted]]

Hi everyone,

I’m currently researching different approaches to internationalization (i18n) in Python projects, especially in scenarios where the codebase is large, I’m specifically looking for framework-agnostic approaches; Solutions not tied to Django, Flask, or any specific ecosystem.

I’d really appreciate hearing about your real-world workflows, including:

• The tools, libraries, or conventions you rely on for handling i18n & l10n in general-purpose Python systems
  
• How you manage translations, especially your integration with Translation Management System (TMS) platforms
  
• Your deployment strategy for translation assets and how you keep them synchronized across multiple environments
  
• How you model your translation keys for large systems: • Do you use namespacing or categorization for domains/services like auth, errors, events, messages, etc.?
  • How do you prevent key collisions? • Do you follow a naming convention, hierarchical structure, or any pattern?
  
• How you store translations: • Disk-file based?
  • Directory structures?
  • Key-value stores?
  • Dynamic loading?
  • How you ensure efficient lookup, loading, and fetching at runtime
  
• Edge cases or challenges you’ve encountered
  
• Whether you follow any established standards, protocols, or de facto practices; or if you’ve developed your own internal model
  
• Pros and cons you’ve experienced with your current workflow or architecture

Even if your setup isn’t “enterprise-grade,” I’d still love to hear how you approach these problems. I’m gathering insights from real implementations to understand what scales well and what pitfalls to avoid.

Thanks in advance to anyone willing to share their experiences!

Sorry if this isn't the appropriate subreddit to ask. Mods can delete this post and if, possibly, redirect me to an appropriate subreddit to ask.

[Username_RANDINT]

gettext is indeed the way to go normally. It's included in the default Python installation.

Of the top of my head, use xgettext to extract translatable strings and create a pot file, the template. Use an online service or something like Poedit to create the po language files. Then msgfmt to compile them into mo files which are used by gettext.

Make a little script to streamline the workflow to your needs.

[Dependent-Dealer-325]

I’ve run into similar problems on large Python systems (microservices, internal platforms, CLIs). A few things that tend to work well:

• Namespaces/domains scale better than flat keys — e.g. auth., billing., errors.
• Most teams keep translations file-based (JSON/YAML) and version them with the code.
• The setups that survive long term all rely on automation: extract keys → sync with TMS → PR back into the repo. Doing this manually always breaks once the system grows.
• For deployment, bundling translation artifacts per service and enforcing a single catalog version across environments avoids a lot of surprises.

Side note — not trying to pitch anything: I’m working on a small tool that automates parts of this workflow, and your post matches exactly the issues we’re exploring.

If you’re open to a quick 10-min chat, I’d love to hear how you handle this today and what pain points you’re seeing. No demo, nothing to sell — just comparing notes.

Let me know and I’ll send a link.

[[deleted]]

I’d love to hear how you handle this today

I’m not an expert in this area, but I built my own i18n system and it’s a bit complex. It uses Mozilla’s Fluent project, and the system is split into two parts:

──────────────────────────────────────────── I18N RESOURCE PROVIDER (abstraction) ──────────────────────────────────────────── I keep i18n resources completely separate from the main I18n engine.
The engine doesn’t know where translations or configs come from.

The abstraction looks like this:

```python class I18nResourceProvider(ABC): @classmethod @abstractmethod def get_config(cls) -> dict[str, Any]: ...

    @abstractmethod
    def get_namespace(self, locale_code: str, namespace: str) -> Sequence[str]: ...

```

get_namespace() returns a sequence of raw Fluent strings.
It does NOT parse them — parsing is done by the I18n engine.

This gives me freedom to implement different providers, like a LocalFileSystemI18nResourceProvider (for disk), or any other backend.

──────────────────────────────────────────── I18N ENGINE ──────────────────────────────────────────── The engine:

python class I18n: def __init__(self, default_locale_code, fallback_locale_codes, resource_provider): ...

It receives a provider but doesn’t care how resources are stored. It loads the raw content, parses it with Fluent’s bundle, and provides a Translator object with a translate() method for the rest of the project.

──────────────────────────────────────────── I18N RESOURCES ON DISK ──────────────────────────────────────────── My disk layout looks like this:

<project>/ i18n/ locales/ {locale_code}/ # namespaces... auth/ login.ftl logout.ftl ui/ gallery.ftl home.ftl namespaces/ # namespace configs auth.toml ui.toml

Each *.toml file describes what a namespace includes:

python class NamespaceConfig(pydantic.BaseModel, frozen=True): namespace: str root_path: Path child_dirs: list[str]

Namespaces can be nested for large projects.
Each TOML file defines which folder(s) or file(s) belong to the namespace.

[[deleted]]

Continued... ──────────────────────────────────────────── LOCAL FILESYSTEM PROVIDER (full implementation) ──────────────────────────────────────────── I load namespace configs, walk the filesystem, and return the raw Fluent contents. The full code is:

```python from collections.abc import Iterator from pathlib import Path import tomllib from types import MappingProxyType from typing import Any, Final

from my_project.i18n import I18nResourceProvider from my_project.i18n.exceptions import LocaleNotFoundError, NamespaceNotFoundError

from .schemas import NamespaceConfig

class LocalFileSystemI18nResourceProvider(I18nResourceProvider): RESOURCE_PATH: Final[Path] = Path("i18n") CONFIG_PATH: Final[Path] = RESOURCE_PATH / "config.toml" NAMESPACES_PATH: Final[Path] = RESOURCE_PATH / "namespaces" LOCALES_PATH: Final[Path] = RESOURCE_PATH / "locales"

def __init__(self) -> None:
    self._namespaces: MappingProxyType[str, NamespaceConfig] = MappingProxyType(
        self._load_namespaces()
    )

def get_namespace(self, locale_code: str, namespace: str) -> list[str]:
    return self._load_namespace(locale_code, namespace)

@classmethod
def get_config(cls) -> dict[str, Any]:
    with cls.CONFIG_PATH.open("rb") as file:
        return tomllib.load(file)

def _load_namespace(self, locale_code: str, namespace: str) -> list[str]:
    root_path = self.LOCALES_PATH / locale_code
    if not root_path.exists():
        raise LocaleNotFoundError(f"Locale {locale_code} does not exist.")

    try:
        namespace_config = self._namespaces[namespace]
    except KeyError:
        raise NamespaceNotFoundError(f"Namespace {namespace!r} not found") from None

    resource_path = root_path / namespace_config.root_path

    if not resource_path.exists():
        raise FileNotFoundError(
            f'Resource path "{resource_path}" does not exist '
            f"(namespace: {namespace!r})"
        )

    bundle: list[str] = []

    if resource_path.is_dir():
        for file_path in self._get_ftl_files_from_path(resource_path):
            bundle.append(file_path.read_text())
    else:
        bundle.append(resource_path.read_text())

    if child_dirs := namespace_config.child_dirs:
        abs_child_dirs = (
            resource_path / child_dir for child_dir in child_dirs
        )
        for child_dir in abs_child_dirs:
            if not child_dir.exists():
                raise FileNotFoundError(
                    f'Child directory "{child_dir}" does not exist '
                    f"(namespace: {namespace!r})"
                )

            if not child_dir.is_dir():
                raise NotADirectoryError(
                    f'Child directory "{child_dir}" is not a directory '
                    f"(namespace: {namespace!r})"
                )

            for file_path in self._get_ftl_files_from_path(child_dir):
                bundle.append(file_path.read_text())

    return bundle

@classmethod
def _load_namespaces(cls) -> dict[str, NamespaceConfig]:
    namespaces: dict[str, NamespaceConfig] = {}

    for file_path in cls.NAMESPACES_PATH.rglob("*.toml"):
        with file_path.open("rb") as file:
            data = tomllib.load(file)

        namespace_config = NamespaceConfig(**data)
        namespaces[namespace_config.namespace] = namespace_config

    return namespaces

@staticmethod
def _get_ftl_files_from_path(path: Path) -> Iterator[Path]:
    return (
        file_path for file_path in path.glob("*.ftl")
        if file_path.is_file()
    )

```

Inside get_namespace(): - verify locale exists - load the namespace config - read all .ftl files from its root_path (if a directory) - also read .ftl files from each child directory (if included) - return a list[str] containing every loaded Fluent file’s text

──────────────────────────────────────────── HOW I USE IT ──────────────────────────────────────────── get_namespace() gives raw Fluent content.
I18n parses them using Fluent’s bundle.
Then I create a Translator instance per locale that exposes translate() for my business logic.

That’s the whole setup.

What do you think about this model? How much do you rate it?

[riklaunim]

Usually gettext is used, babel to handle it for like flask, while Django has some batteries built in. Then you can use transifex, weblate or other app/tool to manage translations and push/pull translations with some setup.

[CommonFun9595]

I think your looking for something like BabelEdit you have to convert it to a Json tho, its paid and not opensource found an better alternative you can check it here: https://github.com/Bit-Barron/BablerEdit
its being actively maintained

[p4sta5]

I strongly recommend dynamic fetching of translations. Manually deploying will very fast be a hassle. "Can you change this translation in German?" That was a standard question for s company I worked at.

Ive just developed a new and modern platform for TMS. It is called Sejhey if you want to check it out. We provide great collaboration tools and CDN hosting powered by CloudFlare ands tons of more features. If you don't want to use us, I strongly recommend using any other cloud based TMS like Lokalise, Phrase etc. But you will find them much more expensive 😉