microsoft / microsoft/pxt-microbit

Add ability to translate user-defined names in shared projects

Open
#6,403 2 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

localization MEF 2026 MEF-high share
Dominant language
TypeScript
Stars
804
Forks
721
Avg merge
2d 9h
Merged PRs (30d)
2

Description

Is your feature request related to a problem? Please describe.
Projects opened from microbit.org in languages other than English will see the blocks translated into the user's language (if supported), but user-defined names such as variable, function and parameter names remain in English. These names are descriptive, so not having them translated makes the code harder to understand.

These projects are:

  1. linked via shared project URLs
  2. embedded via renderblocks
  3. we generate hex files (via pxt build)
  4. in the case of CreateAI, projects we’d like to translate are loaded into MakeCode via the iframe embedding interface

Ideally all these processes would support the same translation mechanism. If it’s a simple scheme then potentially 2-4 can be addressed by the Foundation ahead of interacting with MakeCode.

Describe the solution you'd like
A way to replace the source language (English) variable/function/parameter names and potentially any other user-defined strings in shared projects.

It would be acceptable if the author had to use some kind of distinctive placeholder (e.g. $$name$$). The need for this might depend on the sophistication of the replacement/rewriting mechanism.

Design considerations:

  • As user provided text it would make most sense for the Foundation to be responsible for translating variable/function/parameter name text rather than this being part of MakeCode translations.
  • Timing. It makes more sense to provide translations later, based on our Crowdin sync, rather than up-front for all languages in the project. So for example we could extract it from projects and insert it into Crowdin and then provide it on the URL when linking to a shared project.
  • A placeholder munging approach could work, or a more sophisticated TypeScript/Python AST rewrite & blocks xml update.
  • Placeholders might be more flexible, as they could allow arbitrary strings (e.g. an example name in a name badge project) to be localised. Though this could be supported in addition to a more targeted mechanism for variables/functions/parameters.
  • We note that names also appear in _history.

Example project with naive placeholder approach: https://makecode.microbit.org/S84905-79870-20489-74548

This could be linked to from microbit.org as https://makecode.microbit.org/S84905-79870-20489-74548?$$name$$=nom&$$who$$=qui etc.

Describe alternatives you've considered
Perhaps the only workaround without a technical solution in MakeCode is for us to create a shared project in every supported language for every project that contains user-defined names on microbit.org. Because of our Crowdin-based process it’s not really clear at what point in time we should do this and it has a considerable overhead. So far as I know creating such shared projects would need to be manual.

Another approach could be a way for us to have a variant on sharing links, where MakeCode fetches the project from a Foundation owned URL (likely just static JSON files with an agreed URL structure) which would allow us to perform substitutions from our translations. Arguably scenario (1) above is the only one that can’t be addressed by the Foundation doing replacements. This might have more coordination cost to get up and running and be less useful to anyone else in the same situation.

Other suggestions very welcome.

Additional context
N/A

@microbit-matt-hillsdon

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

No source file or test is named. Start by tracing shared project URLs, renderblocks, pxt build, and the iframe embedding interface, including how user-defined names appear in project history. Done requires an agreed mechanism and implementation scope for translating those names across the described project flows.

Written by the indexing model from the issue text.

Assessment

Tech stack
python, typescript
Domain
internationalization
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.