-
-
Notifications
You must be signed in to change notification settings - Fork 1.5k
[charts] Add a localization provider #17325
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from 5 commits
8b21dd5
4362b15
1033397
8f05a9e
896a175
e825b1f
9c3b2f3
f0ef6bd
5b76242
7a2dfa1
04c984b
5f5392e
f59b08b
5dcdb10
30b2819
c0fc322
5e2576b
b38fcb3
f26cd4c
6ec7df8
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
import * as React from 'react'; | ||
import LocalisationTable from 'docsx/src/modules/components/LocalizationTable'; | ||
import data from './data.json'; | ||
|
||
export default function ChartsLocalisationTableNoSnap() { | ||
return <LocalisationTable data={data} />; | ||
} |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,15 @@ | ||
import * as React from 'react'; | ||
import { BarChart } from '@mui/x-charts/BarChart'; | ||
|
||
export default function CustomLocaleOverlay() { | ||
return ( | ||
<BarChart | ||
loading | ||
localeText={{ loading: 'Data are coming 🧙♂️' }} | ||
series={[]} | ||
height={200} | ||
width={300} | ||
xAxis={[{ scaleType: 'band', data: ['Q1', 'Q2', 'Q3', 'Q4'] }]} | ||
/> | ||
); | ||
} |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,15 @@ | ||
import * as React from 'react'; | ||
import { BarChart } from '@mui/x-charts/BarChart'; | ||
|
||
export default function CustomLocaleOverlay() { | ||
return ( | ||
<BarChart | ||
loading | ||
localeText={{ loading: 'Data are coming 🧙♂️' }} | ||
series={[]} | ||
height={200} | ||
width={300} | ||
xAxis={[{ scaleType: 'band', data: ['Q1', 'Q2', 'Q3', 'Q4'] }]} | ||
/> | ||
); | ||
} |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,8 @@ | ||
<BarChart | ||
loading | ||
localeText={{ loading: 'Data are coming 🧙♂️' }} | ||
series={[]} | ||
height={200} | ||
width={300} | ||
xAxis={[{ scaleType: 'band', data: ['Q1', 'Q2', 'Q3', 'Q4'] }]} | ||
/> |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,10 @@ | ||
[ | ||
{ | ||
"languageTag": "fr-FR", | ||
"importName": "frFR", | ||
"localeName": "French", | ||
"missingKeysCount": 0, | ||
"totalKeysCount": 2, | ||
"githubLink": "https://github.com/mui/mui-x/blob/master/packages/x-charts/src/locales/frFR.ts" | ||
} | ||
] |
Original file line number | Diff line number | Diff line change | ||||
---|---|---|---|---|---|---|
@@ -0,0 +1,117 @@ | ||||||
--- | ||||||
title: Charts - Localization | ||||||
productId: x-charts | ||||||
components: ChartsLocalizationProvider, ChartsDataContainer, ChartsLocalizationProvider | ||||||
--- | ||||||
|
||||||
# Charts - Localization | ||||||
|
||||||
<p class="description">The Charts allows to support users from different locales, with formatting, and localized strings.</p> | ||||||
|
||||||
The default locale of MUI X is English (United States). If you want to use other locales, follow the instructions below. | ||||||
|
||||||
## Translation keys | ||||||
|
||||||
You can use the `localeText` prop to pass in your own text and translations. | ||||||
You can find all the translation keys supported in [the source](https://github.com/mui/mui-x/blob/-/packages/x-charts/src/constants/defaultLocale.ts) | ||||||
in the GitHub repository. | ||||||
In the following example, the labels of the loading overlay are customized. | ||||||
|
||||||
{{"demo": "CustomLocaleOverlay.js", "bg": "inline"}} | ||||||
|
||||||
## Locale text | ||||||
|
||||||
The default locale of MUI X is English (United States). | ||||||
alexfauquette marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
||||||
You can use the theme to configure the locale text: | ||||||
|
||||||
```jsx | ||||||
import { createTheme, ThemeProvider } from '@mui/material/styles'; | ||||||
import { BarChart } from '@mui/x-charts/BarChart'; | ||||||
import { frFR } from '@mui/x-charts/locales'; | ||||||
// Or import { frFR } from '@mui/x-charts-pro/locales'; | ||||||
|
||||||
const theme = createTheme( | ||||||
{ | ||||||
palette: { | ||||||
primary: { main: '#1976d2' }, | ||||||
}, | ||||||
}, | ||||||
frFR, | ||||||
); | ||||||
|
||||||
<ThemeProvider theme={theme}> | ||||||
<BarChart /> | ||||||
</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), you can add `frFR` as a new argument. | ||||||
The same import works for Charts Pro as it's an extension of Charts. | ||||||
|
||||||
```jsx | ||||||
import { createTheme, ThemeProvider } from '@mui/material/styles'; | ||||||
import { BarChart } from '@mui/x-charts/BarChart'; | ||||||
import { frFR } from '@mui/x-charts/locales'; | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Might be clearer
Suggested change
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. That would break the logic we use on all packages and their related example. For now, all packages export locales as follow: import { xxYY } from '@mui/[packageName]/locales'; And for multiple packages, we encourage them to do import { xxYY as [packageName]XxYY } from '@mui/[packageName]/locales'; There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. While doing the update, I understood your point. Exporting an object that contained only the I propose to export |
||||||
import { frFR as dataGridFrFR } from '@mui/x-date-pickers/locales'; | ||||||
import { frFR as pickersFrFR } from '@mui/x-date-pickers/locales'; | ||||||
import { frFR as coreFrFR } from '@mui/material/locale'; | ||||||
|
||||||
const theme = createTheme( | ||||||
{ | ||||||
palette: { | ||||||
primary: { main: '#1976d2' }, | ||||||
}, | ||||||
}, | ||||||
frFR, // x-charts translations | ||||||
dataGridFrFR, // x-data-grid translations | ||||||
pickersFrFR, // x-date-pickers translations | ||||||
coreFrFR, // core translations | ||||||
); | ||||||
|
||||||
<ThemeProvider theme={theme}> | ||||||
<BarChart /> | ||||||
</ThemeProvider>; | ||||||
``` | ||||||
|
||||||
If you want to pass language translations directly to the Data Grid without using `createTheme()` and `ThemeProvider`, you can directly load the language translations from `@mui/x-data-grid/locales`. | ||||||
|
||||||
```jsx | ||||||
import { BarChart } from '@mui/x-charts'; | ||||||
import { nlNL } from '@mui/x-charts/locales'; | ||||||
|
||||||
<BarChart | ||||||
localeText={nlNL.components.MuiChartsLocalizationProvider.defaultProps.localeText} | ||||||
/>; | ||||||
``` | ||||||
|
||||||
### Using ChartsLocalizationProvider | ||||||
|
||||||
If you want to pass language translations without using `createTheme()` and `ThemeProvider`, | ||||||
you can directly load the language translations from the `@mui/x-charts` or `@mui/x-charts-pro` package and pass them to the `ChartsLocalizationProvider`. | ||||||
|
||||||
```jsx | ||||||
import { ChartsLocalizationProvider } from '@mui/x-date-pickers/ChartsLocalizationProvider'; | ||||||
import { deDE } from '@mui/x-date-pickers/locales'; | ||||||
import { DatePicker } from '@mui/x-date-pickers/DatePicker'; | ||||||
|
||||||
<ChartsLocalizationProvider | ||||||
localeText={deDE.components.MuiChartsLocalizationProvider.defaultProps.localeText} | ||||||
> | ||||||
<DatePicker /> | ||||||
</ChartsLocalizationProvider>; | ||||||
``` | ||||||
|
||||||
### Supported locales | ||||||
|
||||||
{{"demo": "ChartsLocalisationTableNoSnap.js", "hideToolbar": true, "bg": "inline"}} | ||||||
|
||||||
You can [find the source](https://github.com/mui/mui-x/tree/HEAD/packages/x-charts/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. | ||||||
alexfauquette marked this conversation as resolved.
Show resolved
Hide resolved
|
||||||
|
||||||
## RTL Support | ||||||
|
||||||
Right-to-left languages such as Arabic, Persian, or Hebrew are supported. | ||||||
Follow [this guide](/material-ui/customization/right-to-left/) to use them. |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,23 @@ | ||
import * as React from 'react'; | ||
import ApiPage from 'docs/src/modules/components/ApiPage'; | ||
import mapApiPageTranslations from 'docs/src/modules/utils/mapApiPageTranslations'; | ||
import jsonPageContent from './charts-localization-provider.json'; | ||
|
||
export default function Page(props) { | ||
const { descriptions, pageContent } = props; | ||
return <ApiPage descriptions={descriptions} pageContent={pageContent} />; | ||
} | ||
|
||
Page.getInitialProps = () => { | ||
const req = require.context( | ||
'docsx/translations/api-docs/charts/charts-localization-provider', | ||
false, | ||
/\.\/charts-localization-provider.*.json$/, | ||
); | ||
const descriptions = mapApiPageTranslations(req); | ||
|
||
return { | ||
descriptions, | ||
pageContent: jsonPageContent, | ||
}; | ||
}; |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,17 @@ | ||
{ | ||
"props": { "localeText": { "type": { "name": "object" } } }, | ||
"name": "ChartsLocalizationProvider", | ||
"imports": [ | ||
"import { ChartsLocalizationProvider } from '@mui/x-charts/ChartsLocalizationProvider';", | ||
"import { ChartsLocalizationProvider } from '@mui/x-charts';", | ||
"import { ChartsLocalizationProvider } from '@mui/x-charts-pro';" | ||
], | ||
"classes": [], | ||
"spread": true, | ||
"themeDefaultProps": null, | ||
"muiName": "MuiChartsLocalizationProvider", | ||
"filename": "/packages/x-charts/src/ChartsLocalizationProvider/ChartsLocalizationProvider.tsx", | ||
"inheritance": null, | ||
"demos": "<ul><li><a href=\"/x/react-charts/localization/\">Charts - Localization</a></li></ul>", | ||
"cssComponent": false | ||
} |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,7 @@ | ||
import * as React from 'react'; | ||
import MarkdownDocs from 'docs/src/modules/components/MarkdownDocs'; | ||
import * as pageProps from 'docsx/data/charts/localization/localization.md?muiMarkdown'; | ||
|
||
export default function Page() { | ||
return <MarkdownDocs {...pageProps} disableAd />; | ||
} |
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.
Should this be called
ChartsLocalizationTableNoSnap
? It seems like we're using enUS spelling