doti18n 0.4.4

Python library for loading localizations with dot access and pluralization.

Type-safe localization library for Python.
Access YAML, JSON, and XML translations using dot-notation.

---

Overview

doti18n allows you to replace string-based dictionary lookups with intuitive object navigation. Instead of locales['en']['messages']['error'], just write locales.en.messages.error.

It focuses on Developer Experience (DX) by providing a CLI tool to generate .pyi stubs. This enables IDE autocompletion and allows static type checkers (mypy, pyright) to catch missing keys at build time.

Key Features

• Dot-Notation: Access nested keys via attributes (data.key) and lists via indices (items[0]).
• Type Safety: Generate stubs to get full IDE support and catch typos instantly.
• Pluralization: robust support powered by Babel.
• Format Agnostic: Supports YAML, JSON, and XML out of the box.
• Safety Modes:
  • Strict: Raises exceptions for missing keys (good for dev/test).
  • Non-strict: Returns a safe wrapper and logs warnings (good for production).
• Fallback: Automatically falls back to the default locale if a key is missing.

Installation

pip install doti18n

If you use YAML files:

pip install doti18n[yaml]

Usage

1. Create a localization file (locales/en.yaml):

greeting: "Hello {}!"
farewell: "Goodbye $name!"
items:
    - name: "Item 1"
    - name: "Item 2"
notifications:
    one: "You have {count} new notification."
    other: "You have {count} new notifications."

2. Access it in Python:

from doti18n import LocaleData

# Initialize (loads and caches data)
i18n = LocaleData("locales")
en = i18n["en"]

# 1. Standard formatting (Python-style)
print(en.greeting("John"))           # Output: Hello John!

# 2. Variable formatting (Shell-style)
print(en.farewell(name="Alice"))     # Output: Goodbye Alice!

# 3. Raw strings and graceful handling
print(en.farewell)                   # Output: Goodbye $name! (Raw string)
print(en.farewell())                 # Output: Goodbye ! (Missing var handled)

# 4. List access
print(en.items[0].name)              # Output: Item 1

# 5. Pluralization
print(en.notifications(1))           # Output: You have 1 new notification.
print(en.notifications(5))           # Output: You have 5 new notifications.

CLI & Type Safety

doti18n comes with a CLI to generate type stubs (.pyi).

Why use it?

1. Autocompletion: Your IDE will suggest available keys as you type.
2. Validation: Static analysis tools will flag errors if you try to access a key that doesn't exist.

Commands:

# Generate stubs for all files in 'locales/' (default lang: en)
python -m doti18n stub locales/

# Generate stubs with a specific default language
python -m doti18n stub locales/ -lang fr

# Clean up generated stubs
python -m doti18n stub --clean

Note: Run this inside your virtual environment to ensure stubs are generated for the installed package.

Project Status

Alpha Stage: The API is stable but may evolve before the 1.0.0 release. Feedback and feature requests are highly appreciated!

Documentation

Documentation is available at:
https://darkj3suss.github.io/doti18n/

License

MIT License. See LICENSE for details.

Contact

• Issues: GitHub Issues
• Direct: Telegram