Home

doti18n is a Python library that allows you to access localization data (YAML, JSON, XML, TOML) using dot-notation instead of dictionary lookups.

It focuses on type safety by generating .pyi stubs, allowing IDEs to provide autocompletion and enabling linters to catch missing keys or other errors.

Comparison#

The main goal of doti18n is to replace string-based lookups with object navigation.

# Traditional dictionary lookup
locales['en']['messages']['errors']['connection']

# gettext style
_("messages.errors.connection")

# doti18n style
i18n["en"].messages.errors.connection

Features#

Type Safety & Autocompletion#

doti18n includes a CLI tool that scans your locale files and generates PEP 561 compatible type stubs.

• IDE Autocompletion: Editors like VS Code and PyCharm will suggest available keys as you type.
• Validation: Static analysis tools (mypy, pyright) will flag errors if you reference a key that doesn't exist in your translation files.

Pluralization#

The library uses Babel for pluralization, ensuring correct rules for different languages. It supports:

• Standard CLDR plural forms (zero, one, two, few, many, other).
• Variable interpolation.
• Nested structures.

Execution Modes#

You can configure how the library handles missing keys:

• Strict Mode: Raises exceptions for invalid paths. Recommended for testing and CI/CD.
• Non-Strict Mode: Returns a safe wrapper object and logs a warning instead of crashing. Recommended for production.

Project Status#

Next Steps#

• Getting started: Installation and initial setup.
• Usage: Supported formats (YAML, JSON, XML), pluralization examples, and interpolation(formatting).
• CLI: Type stubs, linting, and the translation studio.
• Cheatsheet: Quick reference for common use cases and patterns.