Skip to content

Getting Started

Installation#

Install from PyPI:

pip install doti18n

For YAML support, install the extra dependency:

pip install doti18n[yaml]

Or install from source:

git clone https://github.com/darkj3suss/doti18n
cd doti18n
pip install .

First Steps#

Create a directory for your localization files.

Tip

doti18n supports YAML, JSON, XML, and TOML out of the box. You can add other formats via Custom Loaders.

Directory Structure:

project_root/
├── locales/
│   ├── en.yaml
│   ├── fr.yaml
│   └── ...
└── main.py

Create Files#

locales/en.yaml: 

hello: "Hello World!"
locales/fr.yaml: 
hello: "Bonjour le monde!"

locales/en.json: 

{"hello": "Hello World!"}
locales/fr.json: 
{"hello": "Bonjour le monde!"}

Note

The root element is ignored in XML files. See Supported Formats for details.

locales/en.xml: 

<locale>
    <hello>Hello World!</hello>
</locale>
locales/fr.xml: 
<locale>
    <hello>Bonjour le monde!</hello>
</locale>

locales/en.toml: 

hello = "Hello World!"
locales/fr.toml: 
hello = "Bonjour le monde!"

Usage#

Load and access translations using dot-notation:

from doti18n import LocaleData

i18n = LocaleData("locales")

print(i18n["en"].hello)  # Output: Hello World!
print(i18n["fr"].hello)  # Output: Bonjour le monde!

That's it! Check the Usage section for advanced features like pluralization, formatting, and strict mode.