Blockly: Configuring the used locale (for Blockly Web at least) is largely undocumented

[SillyFreak]

Where

In the Guide, I'd have expected to find information at Configure - Web - Language or similar (i.e. as a sibling of Configure - Web - Toolbox etc.)
The Reference is specifically missing an entry for setLocale in the Blockly namespace

What

• [x] Text
• [ ] Image or Gif
• [ ] Other

Old content

none

Suggested content

I found what I needed on the forum, specifically this example code:

import Blockly from 'blockly/core'; // Blockly core
import 'blockly/blocks'; // Blockly blocks
import 'blockly/php'; // PHP Generator
import * as En from 'blockly/msg/en'; // English locale files
Blockly.setLocale(En);

The shape of En would be valuable to describe, as well as patterns for adding translations for custom blocks. I'm using

Blockly.setLocale({ ...En, ...MyEnMsg });

to add custom translations. I'm also thinking about number formats and RTL now, which are not covered by calling setLocale().

(Using words such as "translation" and "locale" in the docs is important as search terms, as "language" is very overloaded in the context of blockly. I think they come naturally in such text anyway, but I thought I might as well mention it).

Additional context

none

[samelhusseini]

Some thoughts on this.

Blockly.setLocale is only available in the npm package.
It probably doesn't have to be.

Agreed that the documentation should be updated, but perhaps also support for setLocale in Blockly for all.

[SillyFreak]

but perhaps also support for setLocale in Blockly for all.

I wanted to limit the scope to documentation, but in terms of what could be done when looking at the localization feature: setLocale applies globally instead of per workspace. In our app we have multiple different Blockly languages, with different blocks and therefore different message sets. This is not a problem in practice, as calling setLocale after loading the workspace does not seem to affect it:

Blockly.setLocale(myMsg1);
Blockly.Xml.clearWorkspaceAndLoadFromXml(dom1, workspace1);

Blockly.setLocale(myMsg2);
Blockly.Xml.clearWorkspaceAndLoadFromXml(dom2, workspace2);

// workspace1 still works and uses the messages it needs

But it would feel more natural to set this per workspace, like e.g. rtl.

[maribethb]

I've added documentation for configuring the locale to the Blockly Developer site: https://developers.google.com/blockly/guides/configure/web/translations

I hope that helps, and feel free to suggest updates you'd like to see. Thanks!