py-toml10n 0.1.3

Simple TOML-based localization manager

py-toml10n

Simple TOML-based localization manager for Python.

Installation

pip install py-toml10n

Quick Start

1. Create localization files

locales/
├── en.toml
└── ru.toml

locales/en.toml:

hello = "Hello"
world = "World"

locales/ru.toml:

hello = "Привет"
world = "Мир"

2. Use in your code

from toml10n import LocalizationManager

LM = LocalizationManager("locales/", default_language="en")

# Get a string in the default language
print(LM.get_string("hello"))  # Hello

# Short syntax
print(LM["hello"])  # Hello

# Get a string in a specific language
print(LM.get_string("hello", language="ru"))  # Привет


# List available languages
print(LM.supported_languages)  # ['en', 'ru']

Features

• Simple — just TOML files, nothing else.

• Thread-safe — safe to use in multi-threaded applications.

• Hot reload — call reload() to pick up changes without restarting.

• Fallback — missing keys fall back to the default language.

• Type hints — full type annotation support.

• Zero dependencies — uses only stdlib tomllib (Python 3.11+).

API Reference

LocalizationManager(locale_dir="locales/", default_language="en")

Initialize the manager and load all .toml files from locale_dir.

locale_dir — path to the folder with .toml files

default_language — language code used when none is specified

---

get_string(key, language=None)

Return a localized string by key.

key — translation key

language — language code, uses default_language if None

Returns the string or [[key]] if not found

---

reload()

Reload all localization files. Useful for hot-reload during development.

---

load_file(filename)

Load a single .toml file by name. supported_languages

Property that returns a list of all loaded language codes.

Exceptions

LocaleDirNotFoundError — the directory doesn't exist

LanguageNotFoundError — requested language is not loaded

LocaleFileLoadError — a TOML file cannot be parsed