TOML

Added in version 3.16.0.

TOML is a common format for configuration files and is increasingly used for localization. The translate toolkit supports two variants of TOML files:

  • Plain TOML files - basic key-value pairs and nested tables.

  • Go i18n TOML files - supports pluralized strings using CLDR plural categories (zero, one, two, few, many, other).

Plain TOML

Plain TOML files contain simple key-value pairs and nested structures:

# Welcome message
welcome = "Welcome to our application"

[settings]
app_name = "My App"
description = "A great application"

[settings.advanced]
timeout = "30 seconds"

Keys are extracted as location identifiers, and comments are preserved as translator notes.

Go i18n TOML

The Go i18n TOML format is commonly used by Go applications and Hugo static site generators. It supports pluralized strings using CLDR plural categories:

[reading_time]
one = "One minute to read"
other = "{{ .Count }} minutes to read"

[items_count]
zero = "No items"
one = "One item"
two = "Two items"
few = "A few items"
many = "Many items"
other = "{{ .Count }} items"

When a table contains 2 or more keys that are all CLDR plural categories (zero, one, two, few, many, other), it is automatically recognized as a plural entry.

To use the Go i18n format, import GoI18nTOMLFile instead of TOMLFile:

from translate.storage.toml import GoI18nTOMLFile

store = GoI18nTOMLFile()
store.parse(content)

Supported Features

  • Nested tables: Tables and nested tables using dot notation (parent.child.key)

  • Arrays: Lists of strings with index notation (list[0])

  • Comments: Developer comments are extracted as translator notes

  • String types: Basic strings, literal strings (single quotes), and multiline strings (triple quotes)

  • Formatting preservation: tomlkit library preserves original formatting during round-trips

  • Plurals (Go i18n only): CLDR plural categories

Non-Conformance

The following are not yet supported:

  • Inline tables with nested structures

  • Date and time values (parsed as strings)

  • Mixed content arrays (only string arrays are localized)

Example Usage

See toml2po for examples of converting TOML files to PO format and back.