Skip to content

Localize generated variable and SpriteKind labels without changing identity - #11615

Open
Christian BR (ChrisesDK) wants to merge 3 commits into
microsoft:masterfrom
ChrisesDK:complete-rendered-label-localization
Open

Christian BR (ChrisesDK) wants to merge 3 commits into
microsoft:masterfrom
ChrisesDK:complete-rendered-label-localization

Conversation

@ChrisesDK

@ChrisesDK Christian BR (ChrisesDK) commented Sep 21, 2026 •

Copy link
Copy Markdown

PXT upstream pull request

Title

Localize generated variable and SpriteKind labels without changing identity

Base and head

  • Base: microsoft/pxt:master
  • Head: ChrisesDK:complete-rendered-label-localization
  • Local branch and commit: complete-rendered-label-localization at
    95be24b3dffb214754245672cad28722397e7d40

Description

Summary

Some pupil-visible generated/default Blockly variable labels and built-in
SpriteKind labels currently render raw identifiers, so they cannot be
localized through the normal MakeCode localization pipeline. This change
separates localized display text from stored and compiler-facing identity.

It adds opt-in, display-only localization for generated/default variable labels
and localized display labels for built-in SpriteKind dropdown members.
When MakeCode automatically uniquifies a generated default variable name,
numbered variants reuse the localized display of the base concept. For example,
generated mySprite2 and mySprite3 display as the localized form of
mySprite followed by the raw suffixes 2 and 3, without creating separate
localization keys.

Compatibility

  • Raw variable model names, variable IDs, and Blockly XML remain unchanged.
  • Generated TypeScript and Python identifiers remain unchanged.
  • Built-in SpriteKind dropdown values remain raw (Player, Projectile,
    Food, and Enemy).
  • Ordinary user-created variables and custom SpriteKinds retain their existing
    behavior; a matching standalone user variable is not globally aliased.
  • The implementation is locale-independent and introduces no locale-specific
    production hardcoding.

Localization surface

This exposes 14 localization concepts:

  • {id:var}anim
  • {id:var}location
  • {id:var}myTile
  • {id:var}tile list
  • {id:var}projectile
  • {id:var}otherSprite
  • {id:var}myEnemy
  • {id:var}picture
  • {id:var}mySprite
  • {id:var}list
  • SpriteKind.Player
  • SpriteKind.Projectile
  • SpriteKind.Food
  • SpriteKind.Enemy

The localization gaps addressed by this change were validated against the
rendered block-label mechanisms observed during a Danish Arcade localization
review. This is implementation-validation context, not formal exhaustive QA.

Validation

  • TypeScript/typecheck passed on the refreshed-base work.
  • Python identity round trip passed: 27/27.
  • A previous focused Blockly/Karma localization run passed: 152/152 on the
    original verified implementation.
  • 611 applicable component tests passed across completed earlier runs.
  • The PXT production build passed on the earlier verified implementation.
  • The Arcade target build passed.

The final branch does not have a fresh complete Karma run: Puppeteer's cached
Chrome executable is unavailable locally. This is an environment block, not an
observed implementation test failure. A final combined rerun stopped after 427
passing tests at that browser-launch step and was not a complete combined run.
No implementation failure has been observed; normal upstream CI is still
expected.

Follow-up

pxt-common-packages has a dependent follow-up that opts the relevant Arcade
library surfaces into this generic PXT capability. PXT must land and be
synchronized before that follow-up is merged.

Out of scope

This source PR deliberately does not include ordinary Crowdin wording fixes,
Crowdin-to-Arcade publication lag, Danish terminology decisions, or enabling
the da locale. Those are separate localization-content and deployment work.

@ChrisesDK

Copy link
Copy Markdown
Author

@microsoft-github-policy-service agree

@ChrisesDK

Copy link
Copy Markdown
Author

Rebased onto current master and confirmed the PR is mergeable again.

Joey Wunderlich (@jwunderl), could you please take a look at the Blockly/localization design when you have capacity? The key invariant is that generated variables and built-in SpriteKind members keep their stored IDs, XML, and compiler-facing values unchanged; only their rendered labels are localized. The refresh also retains the upstream test imports alongside the new focused localization coverage.

The new fork-PR Actions runs are currently at GitHub's action_required approval gate, so a maintainer approval/run would let the normal validation proceed. Happy to make any requested scope or implementation changes.

@jwunderl Joey Wunderlich (jwunderl) left a comment •

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

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

Looks good to me though i'll tag in richard too for a quick look over the pxtblocks changes. Only other thing that comes to mind would be e.g. tutorials where sprite kind is used and translation needs to match between tutorial md text and the code snippets -- I guess should be fine, as the blocks would be rendering out as the translated versions after decompile / just md need to be updated? Can't really get better than that for this sort of thing

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟡 Changes recommended

Unresolved localization defects mishandle numeric suffixes, opt-in settings, and implicit receivers, while causing stale labels, screen-reader mismatches, and custom-kind dropdown failures.

5 open issues
What changed in this PR

Adds framework support for translating generated Blockly variable labels and built-in SpriteKind labels separately from their stored and compiler-facing identities.

Changes:

  • Introduces opt-in variable metadata, localization-key extraction, and translation caching.
  • Adds localized field and dropdown rendering, including numbered default-variable names.
  • Adds display, serialization, extraction, compilation, and Python round-trip coverage.
File Description
tests/​pydecompile-test/​pydecompilerunner.ts Adds variable and SpriteKind identifier round-trip assertions.
tests/​blocklycompiler-test/​test.spec.ts Registers the localized-field test suite.
tests/​blocklycompiler-test/​test-library/​spritekind.ts Adds built-in kind labels and block identity metadata.
tests/​blocklycompiler-test/​localizedFields.spec.ts Tests localized display text and unchanged stored values.
tests/​blocklycompiler-test/​commentparsing.spec.ts Tests variable-key extraction and translation caching.
tests/​blocklycompiler-test/​cases/​sprite_kind.blocks Expands compilation fixtures to cover all built-in kinds.
tests/​blocklycompiler-test/​baselines/​sprite_kind.ts Updates expected SpriteKind compilation output.
pxtlib/​service.ts Collects kind display names and caches variable translations.
pxtlib/​blocks.ts Adds helpers for localizable default-variable names.
pxtcompiler/​emitter/​service.ts Extracts display-only variable localization keys.
pxtblocks/​plugins/​newVariableField/​fieldVariable.ts Adds localization hooks for field and dropdown labels.
pxtblocks/​loader.ts Resolves localization from API context and numeric suffixes.
pxtblocks/​fields/​field_kind.ts Uses kind display labels while retaining raw values.
localtypings/​pxtarget.d.ts Declares the variable-label localization opt-in flag.
libs/​pxt-common/​pxt-core.d.ts Annotates the Array.push receiver for localization.

Review effort: Max

Comment thread pxtblocks/fields/field_kind.ts Resolved
Comment thread pxtblocks/loader.ts Resolved
Comment thread pxtblocks/loader.ts Resolved
@ChrisesDK
Christian BR (ChrisesDK) force-pushed the complete-rendered-label-localization branch from f9692d0 to 75cd0d1 Compare October 30, 2026 23:31
@ChrisesDK

Christian BR (ChrisesDK) commented Oct 30, 2026 •

Copy link
Copy Markdown
Author

Thanks Joey Wunderlich (@jwunderl). Rebasing this branch onto current master is complete, and the refreshed validation passes: 190/190 Blockly/Karma and 27/27 Python decompiler tests.

For tutorials, the stored code-facing SpriteKind and generated variable identities intentionally remain raw; tutorial Markdown localization is a separate content concern. When translated Blockly renders a decompiled snippet, its opted-in display labels use the same localization catalog, so content can align with the rendered blocks without changing program identity.

@ChrisesDK

Christian BR (ChrisesDK) commented Oct 30, 2026 •

Copy link
Copy Markdown
Author

Follow-up on the remaining block-label review threads: all five are now addressed and resolved.

  • custom kinds such as toString cannot inherit a display label from Object.prototype;
  • generated/default labels are used only when the defining API explicitly opted in;
  • generated numeric suffixes now cover canonical values from 2 onward, including 10 and 100;
  • moving a getter or changing its old/new parent refreshes the rendered label; and
  • accessible text follows the same localized display label.

Added regression coverage for those cases. After a clean rebuild, the full Blockly/Karma suite passes: 190/190.

Richard Knoll (@riknoll), Joey suggested a PXTBlocks look-over. This branch now includes the resolved follow-up fixes and is ready for that review.

@ChrisesDK
Christian BR (ChrisesDK) force-pushed the complete-rendered-label-localization branch from 8d34347 to 091b5a7 Compare November 18, 2026 08:37
@ChrisesDK

Copy link
Copy Markdown
Author

Rebased onto current master (a0ef861) and reconciled the upstream Blockly test registrations.

Fresh validation on the rebased branch passes:

  • npm run build -- --no-webapps
  • 239/239 Blockly/Karma tests
  • 27/27 Python decompiler tests

Richard Knoll (@riknoll), the branch is mergeable again and ready for the requested PXTBlocks review.

@ChrisesDK
Christian BR (ChrisesDK) force-pushed the complete-rendered-label-localization branch from 091b5a7 to 20a288a Compare November 21, 2026 11:35
@ChrisesDK

Copy link
Copy Markdown
Author

Rebased again onto current master (19bd210) to clear the behind state.

Fresh validation passes:

  • npm run build -- --no-webapps
  • 239/239 Blockly/Karma tests
  • 27/27 Python decompiler tests

Richard Knoll (@riknoll), the branch is mergeable and ready for the requested PXTBlocks review.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants