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:

Line chart of monthly revenue with German number and month formatting

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.