<NME> localization.mdx
<BEF> ADDFILE
<MSG> some localizer polish

<DFF> @@ -0,0 +1,138 @@
+import TabbedCodeBlock, { Tab } from '../components/TabbedCodeBlock'
+
+# Localization
+
+In order to handle the complex international differences in number and date formats `react-widgets` defaults to using the
+browser [Intl](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl) API's to handle
+localization. For most cases these APIs provide all the necessary tools to handle number and date **formatting**.
+
+For parsing, though the story is less great. Internally `react-widgets` relies on non-locale aware parsing API's like
+`parseFloat` and `new Date()`. This works generally, but if you want more complex
+date parsing, such as parsing via formats, you'll have to provide your own `parse` props to Date/Time pickers or NumberPicker.
+
+For usage with browsers that don't support the required `Intl` API's, _or_ want to broadly customize
+the parsing and formatting behavior of the inputs. The formatting and parsing logic has been
+extracted into pluggable "localizers". Which can be used to adapt commonly used I18n libraries
+such as Moment, Date-fns, Luxon, etc.
+
+Localizer's are split into `DateLocalizer` and `NumberLocalizer` classes to better
+customize which libraries are needed for specific use-cases.
+
+## configuration
+
+Localizer configuration is handled via a top level "Provider" component, exported from `react-widgets`. This should
+ideally rendered close to the root of your App. You can broadly customize the
+default language used by each compoent (via `messages`) and configure date and/or number
+localizer instances.
+
+```tsx
+import { Localization } from 'react-widgets'
+;<Localization messages={customMessages} date={myDateLocalizer}>
+  {app}
+</Localization>
+```
+
+### Moment.js <small>date</small>
+
+```sh
+npm install moment react-widgets-moment --save
+```
+
+Again see the official [Moment docs](http://momentjs.com/) for information on integrating Moment into your build
+pipeline effectively.
+
+Moment only provides **date** localization, if you also need Number localization consider
+the **simple-number** localizer below, or Globalize.js.
+
+```tsx
+import moment from 'moment'
+import MomentLocalizer from 'react-widgets-moment';
+import DateTimePicker from 'react-widgets/lib/DateTimePicker';
+
+moment.locale('en')
+
+const localizer = new MomentLocalizer(moment)
+
+<Localization date={momentLocalizer}>
+```
+
+Moment [format](http://momentjs.com/docs/#/displaying/format/) props accept `string`s
+
+```jsx
+<DateTimePicker format="mmm YYY" />
+```
+
+### date-fns <small>date</small>
+
+```sh
+npm install react-widgets-date-fns date-fns@2.0.0-alpha.7 --save
+```
+
+See the official [date-fns docs](https://date-fns.org/v2.0.0-alpha.7/docs/Getting-Started) for information
+on integrating date-fns.
+
+`date-fns` only provides **date** localization, if you also need Number localization consider
+the **simple-number** localizer below, or Globalize.js.
+
+The `date-fns` localizer is a convenient option to get up and running quickly as it is ready-to-use with
+the `en-US` locale without any configuration, and includes only the `date-fns` bits that are used
+for formatting and parsing dates so the additional bundle size should be minimal.
+
+```tsx
+import DateFnsLocalizer from 'react-widgets-date-fns'
+import DateTimePicker from 'react-widgets/lib/DateTimePicker'
+;<Localization date={new DateFnsLocalizer()}>...</Localization>
+```
+
+Additional locales can be included and date formats overridden by passing them as options to
+the localizer function.
+
+```js
+// Use custom date formats and include all date-fns locales
+import DateFnsLocalizer, { defaultFormats } from 'react-widgets-date-fns'
+import locales from 'date-fns/locale'
+
+const formats = Object.assign(defaultFormats, { default: 'mmm YY' })
+const localizer = new DateFnsLocalizer({ formats, locales })
+
+// Include only the locales you need to limit bundle size
+import enGB from 'date-fns/locale/en-GB'
+import de from 'date-fns/locale/de'
+
+new DateFnsLocalizer({ locales: { 'en-GB': enGB, de: de } })
+```
+
+date-fns [format](https://date-fns.org/v1.29.0/docs/format) props accept `string`s
+
+```jsx
+<DateTimePicker format="mmm YYY" />
+```
+
+### Simple Number <small>number</small>
+
+The `simple-number` localizer provides a minimal token based number formatting and parsing strategy. Its best when you don't need
+robust locale support for currencies, and numbers;
+
+```js
+import SimpleNumberLocalizer from 'react-widgets-simple-number';
+import NumberPicker from 'react-widgets/lib/NumberPicker';
+
+new SimpleNumberLocalizer()
+
+<Localization number={new SimpleNumberLocalizer()}>
+  ...
+</Localization>
+```
+
+Check out the documentation for [format-number-with-string](https://www.npmjs.com/package/format-number-with-string) for
+a complete guide to its format syntax.
+
+```jsx
+<NumberPicker format="-$#,###.00" />
+```
+
+## Creating a Localizer
+
+New localizers are easy to create, either by sub-classing an existing one
+to customize it or by creating a new one entirely by implementing the
+Localizer interface for either Dates or Numbers.

some localizer polish