Add localization documentation

doc/user_guide/customization.rst

@@ -817,5 +817,45 @@ If you want to restore the default theme, use:
 
 For more ideas on themes, see the `Vega Themes`_ repository.
 
+Localization
+------------
+The preferred format of numbers, dates, and currencies varies by language and locale.
+Vega-Altair takes advantage of `D3's localization support`_ to make it easy to configure
+the locale for your chart using the global ``alt.renderers.set_embed_options`` function.
+
+.. altair-plot::
+   :output: none
+
+   import altair as alt
+   alt.renderers.set_embed_options(
+       formatLocale=format_locale, timeFormatLocale=time_format_locale
+   )
+
+Here ``format_locale`` and ``time_format_locale`` may either be D3 format dictionaries,
+or strings with the names of pre-defined locales. For example, here we use the
+Italian locale (named `it-IT`) for both currencies and dates:
+
+.. altair-plot::
+   :output: none
+
+   import altair as alt
+   from vega_datasets import data
+
+   alt.renderers.set_embed_options(timeFormatLocale="it-IT", formatLocale="it-IT")
+
+   source = data.stocks.url
+   chart = alt.Chart(source).mark_area().transform_filter('year(datum.date) == 2009').encode(
+       x='date:T',
+       y=alt.Y('price:Q', axis=alt.Axis(format="$.0f")),
+       color='symbol:N'
+   )
+   chart
+
+.. image:: /_static/stocks_it-IT.svg
+  :alt: Area chart of stock prices using Italian locale
+
+See https://unpkg.com/d3-format/locale/ for a list of available format locale names, and
+see https://unpkg.com/d3-time-format/locale/ for a list of available time format locales.
 
 .. _Vega Themes: https://github.com/vega/vega-themes/
+.. _`D3's localization support`: https://d3-wiki.readthedocs.io/zh-cn/master/Localization/