Skip to content

improve docs on loading and applying locales #2683

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.

Sign up for GitHub

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

Closed
wants to merge 1 commit into from
Closed

improve docs on loading and applying locales #2683

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
23 changes: 15 additions & 8 deletions dist/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,25 +36,32 @@ You can grab the relevant MathJax files in `./dist/extras/mathjax/`.
### To include localization

Plotly.js defaults to US English (en-US) and includes British English (en) in the standard bundle.
Many other localizations are available - here is an example using Swiss-German (de-CH),
see the contents of this directory for the full list.
They are also available on our CDN as https://cdn.plot.ly/plotly-locale-de-ch-latest.js OR https://cdn.plot.ly/plotly-locale-de-ch-1.38.1.js
Note that the file names are all lowercase, even though the region is uppercase when you apply a locale.
This example uses Swiss-German (de-CH), but many other localizations are available (see the contents of this directory for the full list). All available locales have working date localizations, but only a subset will localize on-graph text (e.g., modebar controls). See [here](https://github.com/plotly/plotly.js/pulls?q=is%3Apr+label%3A%22type%3A+translation%22+is%3Aclosed) for a list of "fully-supported" locales.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Perhaps even better, we could ask translation authors to add an entry in a table of "fully" supported localizaion instead of linking to a list of PRs/


*After* the plotly.js script tag, add:
#### Loading and registering locales

Some locales build on other locales (e.g., "de-CH" builds on "de"). In this case, first load the base locale (e.g., "de"), then load the actual locale (e.g., "de-CH"):

```html
<script src="plotly-locale-de.js"></script>
Copy link
Contributor

@etpinard etpinard May 31, 2018 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this section is misleading. A priori de-CH doesn't depend on de. At the moment, de-CH fallbacks to de just because de-CH isn't "fully" supported.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So, I propose we use a "fully" supported language for this example and invite folks we want to use a non-fully supported localization (e.g. de-CH) to contribute by making a PR.

<script src="plotly-locale-de-ch.js"></script>
```

Locale bundles are also available on our CDN (e.g., https://cdn.plot.ly/plotly-locale-de-ch-latest.js OR https://cdn.plot.ly/plotly-locale-de-ch-1.38.1.js). Note that the file names here are all lowercase, but the region is uppercase when you apply a locale.

#### Apply a locale

After registering a locale, you can it as the default for all Plotly plots:

```html
<script>Plotly.setPlotConfig({locale: 'de-CH'})</script>
```

The first line loads and registers the locale definition with plotly.js, the second sets it as the default for all Plotly plots.
You can also include multiple locale definitions and apply them to each plot separately as a `config` parameter:
Or, apply the (registered) locale to particular plot(s) as a `config` parameter:

```js
Plotly.newPlot(graphDiv, data, layout, {locale: 'de-CH'})
```

# Bundle information

The main plotly.js bundle includes all the official (non-beta) trace modules.
Expand Down
25 changes: 16 additions & 9 deletions tasks/stats.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,25 +70,32 @@ function getInfoContent() {
'### To include localization',
'',
'Plotly.js defaults to US English (en-US) and includes British English (en) in the standard bundle.',
'Many other localizations are available - here is an example using Swiss-German (de-CH),',
'see the contents of this directory for the full list.',
'They are also available on our CDN as ' + cdnRoot + 'locale-de-ch-latest.js OR ' + cdnRoot + 'locale-de-ch-' + pkg.version + '.js',
'Note that the file names are all lowercase, even though the region is uppercase when you apply a locale.',
'This example uses Swiss-German (de-CH), but many other localizations are available (see the contents of this directory for the full list). All available locales have working date localizations, but only a subset will localize on-graph text (e.g., modebar controls). See [here](https://github.com/plotly/plotly.js/pulls?q=is%3Apr+label%3A%22type%3A+translation%22+is%3Aclosed) for a list of "fully-supported" locales.',
'',
'*After* the plotly.js script tag, add:',
'#### Loading and registering locales',
'',
'Some locales build on other locales (e.g., "de-CH" builds on "de"). In this case, first load the base locale (e.g., "de"), then load the actual locale (e.g., "de-CH"):',
'',
'```html',
'<script src="plotly-locale-de.js"></script>',
'<script src="plotly-locale-de-ch.js"></script>',
'```',
'',
'Locale bundles are also available on our CDN (e.g., ' + cdnRoot + 'locale-de-ch-latest.js OR ' + cdnRoot + 'locale-de-ch-' + pkg.version + '.js). Note that the file names here are all lowercase, but the region is uppercase when you apply a locale.',
'',
'#### Apply a locale',
'',
'After registering a locale, you can it as the default for all Plotly plots:',
'',
'```html',
'<script>Plotly.setPlotConfig({locale: \'de-CH\'})</script>',
'```',
'',
'The first line loads and registers the locale definition with plotly.js, the second sets it as the default for all Plotly plots.',
'You can also include multiple locale definitions and apply them to each plot separately as a `config` parameter:',
'Or, apply the (registered) locale to particular plot(s) as a `config` parameter:',
'',
'```js',
'Plotly.newPlot(graphDiv, data, layout, {locale: \'de-CH\'})',
'```',
''
'```'
];
}

Expand Down