[pickers] Add l10n support #4517
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,58 @@ | ||
| import * as React from 'react'; | ||
| import frLocale from 'date-fns/locale/fr'; | ||
| import ruLocale from 'date-fns/locale/ru'; | ||
| import deLocale from 'date-fns/locale/de'; | ||
| import enLocale from 'date-fns/locale/en-US'; | ||
| import ToggleButton from '@mui/material/ToggleButton'; | ||
| import ToggleButtonGroup from '@mui/material/ToggleButtonGroup'; | ||
| import TextField from '@mui/material/TextField'; | ||
| import { AdapterDateFns } from '@mui/x-date-pickers/AdapterDateFns'; | ||
| import { DatePicker } from '@mui/x-date-pickers/DatePicker'; | ||
| import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider'; | ||
|
|
||
| const localeMap = { | ||
| en: enLocale, | ||
| fr: frLocale, | ||
| ru: ruLocale, | ||
| de: deLocale, | ||
| }; | ||
|
|
||
| const maskMap = { | ||
| fr: '__/__/____', | ||
| en: '__/__/____', | ||
| ru: '__.__.____', | ||
| de: '__.__.____', | ||
| }; | ||
|
|
||
| export default function LocalizedDatePicker() { | ||
| const [locale, setLocale] = React.useState('ru'); | ||
| const [value, setValue] = React.useState(new Date()); | ||
|
|
||
| const selectLocale = (newLocale) => { | ||
| setLocale(newLocale); | ||
| }; | ||
|
|
||
| return ( | ||
| <LocalizationProvider dateAdapter={AdapterDateFns} locale={localeMap[locale]}> | ||
| <div> | ||
| <ToggleButtonGroup value={locale} exclusive sx={{ mb: 2, display: 'block' }}> | ||
| {Object.keys(localeMap).map((localeItem) => ( | ||
| <ToggleButton | ||
| key={localeItem} | ||
| value={localeItem} | ||
| onClick={() => selectLocale(localeItem)} | ||
| > | ||
| {localeItem} | ||
| </ToggleButton> | ||
| ))} | ||
| </ToggleButtonGroup> | ||
| <DatePicker | ||
| mask={maskMap[locale]} | ||
| value={value} | ||
| onChange={(newValue) => setValue(newValue)} | ||
| renderInput={(params) => <TextField {...params} />} | ||
| /> | ||
| </div> | ||
| </LocalizationProvider> | ||
| ); | ||
| } |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,58 @@ | ||
| import * as React from 'react'; | ||
| import frLocale from 'date-fns/locale/fr'; | ||
| import ruLocale from 'date-fns/locale/ru'; | ||
| import deLocale from 'date-fns/locale/de'; | ||
| import enLocale from 'date-fns/locale/en-US'; | ||
| import ToggleButton from '@mui/material/ToggleButton'; | ||
| import ToggleButtonGroup from '@mui/material/ToggleButtonGroup'; | ||
| import TextField from '@mui/material/TextField'; | ||
| import { AdapterDateFns } from '@mui/x-date-pickers/AdapterDateFns'; | ||
| import { DatePicker } from '@mui/x-date-pickers/DatePicker'; | ||
| import { LocalizationProvider } from '@mui/x-date-pickers/LocalizationProvider'; | ||
|
|
||
| const localeMap = { | ||
| en: enLocale, | ||
| fr: frLocale, | ||
| ru: ruLocale, | ||
| de: deLocale, | ||
| }; | ||
|
|
||
| const maskMap = { | ||
| fr: '__/__/____', | ||
| en: '__/__/____', | ||
| ru: '__.__.____', | ||
| de: '__.__.____', | ||
| }; | ||
|
|
||
| export default function LocalizedDatePicker() { | ||
| const [locale, setLocale] = React.useState<keyof typeof maskMap>('ru'); | ||
| const [value, setValue] = React.useState<Date | null>(new Date()); | ||
|
|
||
| const selectLocale = (newLocale: any) => { | ||
|
There was a problem hiding this comment. We can probably type it correctly Create a There was a problem hiding this comment. This is a copy past from other pages so I created a dedicated issue #4915 |
||
| setLocale(newLocale); | ||
| }; | ||
|
|
||
| return ( | ||
| <LocalizationProvider dateAdapter={AdapterDateFns} locale={localeMap[locale]}> | ||
flaviendelangle marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| <div> | ||
| <ToggleButtonGroup value={locale} exclusive sx={{ mb: 2, display: 'block' }}> | ||
| {Object.keys(localeMap).map((localeItem) => ( | ||
| <ToggleButton | ||
| key={localeItem} | ||
| value={localeItem} | ||
| onClick={() => selectLocale(localeItem)} | ||
| > | ||
| {localeItem} | ||
| </ToggleButton> | ||
| ))} | ||
| </ToggleButtonGroup> | ||
| <DatePicker | ||
| mask={maskMap[locale]} | ||
| value={value} | ||
| onChange={(newValue) => setValue(newValue)} | ||
| renderInput={(params) => <TextField {...params} />} | ||
| /> | ||
| </div> | ||
| </LocalizationProvider> | ||
| ); | ||
| } | ||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,105 @@ | ||||||
| --- | ||||||
| title: Pickers - Localization | ||||||
| --- | ||||||
|
|
||||||
| # Pickers - Localization | ||||||
|
|
||||||
| <p class="description">Pickers allow to support users from different locales, with formatting, RTL, and localized strings.</p> | ||||||
|
There was a problem hiding this comment.
Suggested change
The official naming of the project is "Date and time pickers" Same for the title I think On the Getting Start page we have "Date / Time pickers" which is not great I think (https://mui.com/x/react-date-pickers/getting-started/) @samuelsycamore I you have a preference |
||||||
|
|
||||||
| The default locale of MUI is English (United States). If you want to use other locales, follow the instructions below. | ||||||
|
|
||||||
| ## Localization | ||||||
alexfauquette marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
|
||||||
| Localization can impact pickers components rendering in two distincts ways: The date format, and the components attributes such as `aria-label`. | ||||||
|
|
||||||
| ### Date-engine locale | ||||||
|
There was a problem hiding this comment. Not a fan a |
||||||
|
|
||||||
| Use `LocalizationProvider` to change the date-engine locale that is used to render pickers. Here is an example of changing the locale for the `date-fns` adapter: | ||||||
|
|
||||||
| {{"demo": "LocalizedDatePicker.js"}} | ||||||
|
|
||||||
| ### Translation keys | ||||||
|
|
||||||
| As the rest of MUI components, you can modify text and translations. | ||||||
alexfauquette marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| You can find all the translation keys supported in [the source](https://github.com/mui/mui-x/blob/HEAD/packages/grid/x-date-pickers/src/locales/utils/pickersLocaleTextApi.ts) | ||||||
| in the GitHub repository. | ||||||
|
|
||||||
| You can set the locale text by using the theme provider. | ||||||
|
|
||||||
| ```jsx | ||||||
| import { createTheme, ThemeProvider } from '@mui/material/styles'; | ||||||
| import { CalendarPicker, LocalizationProvider, bgBG } from '@mui/x-date-pickers'; | ||||||
| import { AdapterDateFns } from '@mui/x-date-pickers/AdapterDateFns'; | ||||||
|
|
||||||
| const theme = createTheme( | ||||||
| { | ||||||
| palette: { | ||||||
| primary: { main: '#1976d2' }, | ||||||
| }, | ||||||
| }, | ||||||
| bgBG, | ||||||
| ); | ||||||
|
|
||||||
| <ThemeProvider theme={theme}> | ||||||
| <LocalizationProvider dateAdapter={AdapterDateFns}> | ||||||
| <CalendarPicker /> | ||||||
| </LocalizationProvider> | ||||||
| </ThemeProvider>; | ||||||
| ``` | ||||||
|
|
||||||
| Note that `createTheme` accepts any number of arguments. | ||||||
| If you are already using the [translations of the core components](/material-ui/guides/localization/#locale-text) or the [translations of the data grid](/x/react-data-grid/localization/#locale-text), you can add `bgBG` as a new argument. | ||||||
| The same import works for `DataGridPro` as it's an extension of `DataGrid`. | ||||||
|
|
||||||
| ```jsx | ||||||
| import { createTheme, ThemeProvider } from '@mui/material/styles'; | ||||||
| import { DataGrid, bgBG as dataGridBgBG } from '@mui/x-data-grid'; | ||||||
| import { bgBG as coreBgBG } from '@mui/material/locale'; | ||||||
|
|
||||||
| import { CalendarPicker, LocalizationProvider, bgBG } from '@mui/x-date-pickers'; | ||||||
| import { AdapterDateFns } from '@mui/x-date-pickers/AdapterDateFns'; | ||||||
|
|
||||||
| const theme = createTheme( | ||||||
| { | ||||||
| palette: { | ||||||
| primary: { main: '#1976d2' }, | ||||||
| }, | ||||||
| }, | ||||||
| bgBG, // x-date-pickers translations | ||||||
| dataGridBgBG, // x-data-grid translations | ||||||
| coreBgBG, // core translations | ||||||
alexfauquette marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
| ); | ||||||
|
|
||||||
| <ThemeProvider theme={theme}> | ||||||
| <LocalizationProvider dateAdapter={AdapterDateFns}> | ||||||
| <CalendarPicker /> | ||||||
| <DataGrid /> | ||||||
| </LocalizationProvider> | ||||||
| </ThemeProvider>; | ||||||
| ``` | ||||||
|
|
||||||
| If you want to pass language translations without using `createTheme` and `ThemeProvider`, you can directly load the language translations from the `@mui/x-date-pickers` or `@mui/x-date-pickers-pro` package and pass them to the `LocalizationProvider`. | ||||||
|
|
||||||
| ```jsx | ||||||
| import { AdapterDateFns } from '@mui/x-date-pickers/AdapterDateFns'; | ||||||
| import { CalendarPicker, LocalizationProvider, bgBG } from '@mui/x-date-pickers'; | ||||||
|
|
||||||
| <LocalizationProvider | ||||||
| dateAdapter={AdapterDateFns} | ||||||
| localeText={bgBG.components.MuiLocalizationProvider.defaultProps.localeText} | ||||||
| > | ||||||
| <CalendarPicker /> | ||||||
| </LocalizationProvider>; | ||||||
| ``` | ||||||
|
|
||||||
| ### Supported locales | ||||||
|
|
||||||
| | Locale | BCP 47 language tag | Import name | | ||||||
| | :---------------------- | :------------------ | :---------- | | ||||||
| | English (United States) | en-US | `enUS` | | ||||||
| | French | fr-FR | `frFR` | | ||||||
|
|
||||||
| You can [find the source](https://github.com/mui/mui-x/tree/HEAD/packages/grid/x-date-pickers/src/locales) in the GitHub repository. | ||||||
|
|
||||||
| To create your own translation or to customize the English text, copy this file to your project, make any changes needed and import the locale from there. | ||||||
| Note that these translations of the Data grid component depend on the [Localization strategy](/material-ui/guides/localization/) of the whole library. | ||||||
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Just realized this rule was not applied