Number and Time Locales#
Locales control how Vega formats certian values. format_locale sets number formatting options such as decimal marks, digit grouping, and currency symbols. time_format_locale sets the names and patterns used for dates and times.
Use a built-in locale name such as de-DE or ja-JP for standard regional formats, or pass a locale object for custom rules. The built-in names match the locale files in d3-format and d3-time-format. Locales change formatting only. They do not change the timezone or the data.
Use a Built-In Locale#
This chart uses de-DE (German language) as both the number and time locale. This alters the display of the $,.0f numeric format pattern on the y-axis and the display of month names on the x-axis.
Save this specification:
chart.vl.json
{
"$schema": "https://vega.github.io/schema/vega-lite/v6.json",
"title": "Monthly Revenue",
"width": 380,
"height": 180,
"data": {
"values": [
{"month": "2025-01-01", "revenue": 12500},
{"month": "2025-02-01", "revenue": 13800},
{"month": "2025-03-01", "revenue": 15200},
{"month": "2025-04-01", "revenue": 14100},
{"month": "2025-05-01", "revenue": 16900},
{"month": "2025-06-01", "revenue": 18400},
{"month": "2025-07-01", "revenue": 17600},
{"month": "2025-08-01", "revenue": 19300},
{"month": "2025-09-01", "revenue": 21000},
{"month": "2025-10-01", "revenue": 20400},
{"month": "2025-11-01", "revenue": 22700},
{"month": "2025-12-01", "revenue": 25100}
]
},
"mark": {"type": "line", "point": true},
"encoding": {
"x": {"field": "month", "type": "temporal", "scale": {"type": "utc"}, "title": null},
"y": {"field": "revenue", "type": "quantitative", "axis": {"format": "$,.0f"}, "title": null}
}
}
from pathlib import Path
import vl_convert as vlc
spec = Path("chart.vl.json").read_text(encoding="utf-8")
svg = vlc.vegalite_to_svg(
spec,
format_locale="de-DE",
time_format_locale="de-DE",
)
Path("chart.svg").write_text(svg, encoding="utf-8")
Rendered with de-DE locale for both settings, the y-axis groups thousands with a dot and places the euro sign after the number, and the x-axis uses German month names:
Define Custom Number Rules#
A number locale follows the d3-format locale definition. Save this example as format-locale.json:
format-locale.json
{
"decimal": ",",
"thousands": ".",
"grouping": [3],
"currency": ["", " EUR"]
}
Pass the equivalent dictionary:
format_locale = {
"decimal": ",",
"thousands": ".",
"grouping": [3],
"currency": ["", " EUR"],
}
svg = vlc.vegalite_to_svg(spec, format_locale=format_locale)
Custom time locales follow the d3-time-format locale definition and define day and month names as well as date and time patterns. Prefer a built-in name when one fits.
get_format_locale() and get_time_format_locale() return the definition of a built-in locale, and Python Sync API Reference lists the accepted names.
See Configuration to apply a locale to every conversion by default.