Cheatsheet

doti18n is a Python library for accessing localization data (YAML, JSON, XML, TOML) using dot-notation, with built-in type safety, pluralization, macrosing, and ICU Message Format (ICUMF) support.

Installation#

pip install doti18n        # Default (JSON, XML, TOML)
pip install doti18n[yaml]  # With YAML support

Basic Setup & Access#

greeting: "Hello World!"

{
  "greeting": "Hello World!"
}

<locale>
  <greeting>Hello World!</greeting>
</locale>

greeting = "Hello World!"

Python Usage:

from doti18n import LocaleData

i18n = LocaleData("locales")

# Access as raw string
print(i18n["en"].greeting)   # Output: Hello World!

File Structure Examples#

# key-value
hello: "Hello World!"

# list
fruits:
    - "Apple"
    - "Banana"
    - "Orange"

# nested list
items:
    - name: "Item 1" 
    - name: "Item 2"

# nested dict
errors:
    connection: "Connection error occurred."
    timeout: "Request timed out."

# pluralization
notifications:
    one: "You have {count} new notification."
    other: "You have {count} new notifications."

{
    // key-value
    "hello": "Hello World!",

    // list
    "fruits": [
        "Apple",
        "Banana",
        "Orange"
    ],        

    // nested list
    "items": [
        {"name": "Item 1"},
        {"name": "Item 2"}
    ],

    // nested dict
    "errors": {
        "connection": "Connection error occurred.",
        "timeout": "Request timed out."
    },

    // pluralization
    "notifications": {
        "one": "You have {count} new notification.",
        "other": "You have {count} new notifications."
    }
}

<locale>
    <!-- key-value -->
    <hello>Hello World!</hello>

    <!-- list -->
    <fruits list="true">
        <fruit>Apple</fruit>
        <fruit>Banana</fruit>
        <fruit>Orange</fruit>
    </fruits>

    <!-- nested list -->
    <items list="true">
        <item>
            <name>Item 1</name>
        </item>
        <item>
            <name>Item 2</name>
        </item>
    </items>

    <!-- nested dict -->
    <errors>
        <connection>Connection error occurred.</connection>
        <timeout>Request timed out.</timeout>
    </errors>

    <!-- pluralization -->
    <notifications>
        <one>You have {count} new notification.</one>
        <other>You have {count} new notifications.</other>
    </notifications>
</locale>

# key-value
hello = "Hello World!"

# list
fruits = [
    "Apple",
    "Banana",
    "Orange"
]

# nested list
[[items]]
name = "Item 1"
[[items]]
name = "Item 2"

# nested dict
[errors]
connection = "Connection error occurred."
timeout = "Request timed out."

# pluralization
[notifications]
one = "You have {count} new notification."
other = "You have {count} new notifications."

Multilocale#

For more information, see Supported Formats.

__locale__: "en"
hello: "Hello!"
---
__locale__: "fr"
hello: "Bonjour!"

[
  {"__locale__": "en", "hello": "Hello!"},
  {"__locale__": "fr", "hello": "Bonjour!"}
]

<locales>
  <en><hello>Hello!</hello></en>
  <fr><hello>Bonjour!</hello></fr>
</locales>

[[locales]]
__locale__ = "en"
hello = "Hello!"

[[locales]]
__locale__ = "fr"
hello = "Bonjour!"

Macros#

Macros are resolved once at load-time. Use the __macros__ or __doti18n__ key and the @ prefix.
For more information, see Macros.

__macros__:
  brand: "doti18n"

welcome: "Welcome to @brand!"

{
  "__macros__": {
    "brand": "doti18n"
  },
  "welcome": "Welcome to @brand!"
}

<locale>
  <__macros__>
    <brand>doti18n</brand>
  </__macros__>
  <welcome>Welcome to @brand!</welcome>
</locale>

welcome = "Welcome to @brand!"

[__macros__]
brand = "doti18n"

Python Usage:

print(i18n["en"].welcome)  # Output: Welcome to doti18n!

Formatting Styles#

Call the key as a function () to apply formatting. doti18n supports Python formatting natively.
For more information, see Formatting.

Pluralization#

For more information, see Pluralization.

cat:
  one: "{count} cat"
  other: "{count} cats"

{
  "cat": {
    "one": "{count} cat",
    "other": "{count} cats"
  }
}

<locale>
  <cat>
    <one>{count} cat</one>
    <other>{count} cats</other>
  </cat>
</locale>

[cat]
one = "{count} cat"
other = "{count} cats"

Python Usage:

print(i18n["en"].cat(1))  # Output: 1 cat
print(i18n["en"].cat(5))  # Output: 5 cats

ICU Message Format (ICUMF)#

Powered by CLDR rules. Pass variables as keyword arguments. Use # inside sub-numeric formatters to represent the count.
For more information, see ICU Message Format.

Plural#

cats: "{count, plural, one {# cat} other {# cats}}"

{
  "cats": "{count, plural, one {# cat} other {# cats}}"
}

<locale>
  <cats>{count, plural, one {# cat} other {# cats}}</cats>
</locale>

cats = "{count, plural, one {# cat} other {# cats}}"

Python Usage:

i18n["en"].cats(count=5)  # Output: 5 cats

Select (Switch-case)#

status: "{gender, select, male {He} female {She} other {They}}"

{
  "status": "{gender, select, male {He} female {She} other {They}}"
}

<locale>
  <status>{gender, select, male {He} female {She} other {They}}</status>
</locale>

status = "{gender, select, male {He} female {She} other {They}}"

Python Usage:

i18n["en"].status(gender="female")  # Output: She

Selectordinal#

rank: "{pos, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}"

{
  "rank": "{pos, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}"
}

<locale>
  <rank>{pos, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}</rank>
</locale>

rank = "{pos, selectordinal, one {#st} two {#nd} few {#rd} other {#th}}"

Python Usage:

i18n["en"].rank(pos=3)  # Output: 3rd

Configuration Modes#

Control how doti18n handles missing keys during initialization.
For more information, see Configuration.

# Non-Strict Mode (Default) - Recommended for Production
i18n = LocaleData("locales", strict=False)
val = i18n["en"].missing_key 
# Returns NoneWrapper (behaves like None), logs a WARNING. Does NOT crash.

# Strict Mode - Recommended for Development/Testing
i18n = LocaleData("locales", strict=True)
val = i18n["en"].missing_key 
# Raises KeyError!

CLI Tools#

1. Type Stubs (.pyi)#

Generates type definitions for IDE autocompletion and static analysis (mypy).
For more information, see Stub Generation.

Place section types in the root of your locale file to specify explicit types for variables. The generator will import these types (if needed) into the stub file.

__types__:
  name: "str"
  user: "app.models.User"

greeting: "Hello, {name}!"
user_info: "User {user.name} has email {user.email}."

{
  "__types__": {
    "name": "str",
    "user": "app.models.User"
  },
  "greeting": "Hello, {name}!",
  "user_info": "User {user.name} has email {user.email}."
}

<locale>
  <__types__>
    <name>str</name>
    <user>app.models.User</user>
  </__types__>
  <greeting>Hello, {name}!</greeting>
  <user_info>User {user.name} has email {user.email}.</user_info>
</locale>

greeting = "Hello, {name}!"
user_info = "User {user.name} has email {user.email}."
[__types__]
name = "str"
user = "app.models.User"

doti18n stub locales/           # Generate stubs (default source: 'en')
doti18n stub locales/ --lang fr # Use 'fr' as the source of truth
doti18n stub --clean            # Remove generated stubs

2. Linter#

Checks for missing keys, type mismatches, and list length differences between locales.
For more information, see Linting Translations.

doti18n lint locales/             # Lint against 'en' (default)
doti18n lint locales/ --source fr # Lint against 'fr'
doti18n lint locales/ --icumf     # Enable ICU syntax validation

3. Studio#

A web-based translation editor. Multiple users can edit translations simultaneously with real-time sync.
For more information, see Studio.

pip install doti18n[studio]              # Install studio dependencies
doti18n studio add-user admin mypassword # Create a user
doti18n studio run locales/              # Start the editor on http://127.0.0.1:5000

Advanced Customization#

• Custom Formatters: Inherit from BaseFormatter.
• Custom Loaders: Inherit from BaseLoader.
• Custom Tag Handling (HTML to Markdown, etc.): Pass tag_formatter=MarkdownFormatter() to the ICUMF configuration. Or call keys with formatter=MarkdownFormatter() to apply Markdown formatting at runtime.