Skip to content

Adopt ui-core's loc system; retire the Crowdin pipeline#152

Merged
humanapp merged 4 commits into
mainfrom
humanapp/loc
Jul 23, 2026
Merged

Adopt ui-core's loc system; retire the Crowdin pipeline#152
humanapp merged 4 commits into
mainfrom
humanapp/loc

Conversation

@humanapp

Copy link
Copy Markdown
Contributor

Adopt the loc runtime end to end; retire the Crowdin pipeline

Moves all on-device text through the ui-core localization runtime, converts
the legacy translations into source-string-keyed catalogs maintained in-repo,
and replaces the Crowdin build scripts with a per-language build
generator. English builds are behavior-identical (fonts resolve to the same
bitmaps.font8 object; strings resolve to their source values).

What changed

Runtime adoption

  • tooltips.ts rewritten as a derived file: an id -> source-string map
    (tooltipTable) plus tooltip(id), with resolveTooltip(id) now
    returning ui.loc(tooltip(id)). tooltip2tid preserved for the web-only
    tooling. Regenerated from locales/tooltips.json by
    scripts/tooltipgen.mjs (single source of truth; regeneration is
    byte-stable). The orphaned lang/font constants are removed.
  • Fonts: control styles no longer bake font: bitmaps.font8 (the ui-controls
    render fallback resolves locFont() at use time); direct draw/measure
    sites call ui.locFont(). The ControlPicker title now passes an explicit
    font, closing the last draw of localized text that relied on font
    auto-selection. The home-screen tagline and version deliberately stay in
    font5.
  • Raw literals wrapped at use sites ("OK", the settings-screen strings).
    The missing "delete" tooltip key is added, and the tile-suggestion delete
    button's style now composes FocusLabel, so its label renders on focus
    like its grid siblings instead of inline.
  • loc.g.ts (new, first in the pxt.json files list): the per-language
    translation table slot. The committed default assigns nothing; its header
    documents why the file exists, the load-order constraint, and that
    non-default states are transient build intermediates.

Catalogs

  • locales/tooltips.json is the id-keyed master; locales/<lang>.json are
    source-string-keyed translation catalogs for 23 languages, converted from
    the legacy assets/strings data and then filled to ~97% coverage (the
    remaining gaps are dead-tile placeholders and a short low-confidence list
    documented for native review). Missing keys fall back to the source string
    at runtime, so partial catalogs are always safe.
  • locales/README.md documents the catalog rules, the add-a-string workflow,
    coverage checking, and the constraints that preclude CJK support on this
    platform (font, flash, rendering); the four CJK catalogs are kept as data.

Tooling

  • scripts/locgen.mjs: merges the ui-core, ui-controls, and app catalogs
    (app wins), drops identity entries, validates every translation against
    font8's actual glyph table (tagline against font5, since it renders in the
    small font), emits loc.g.ts, and builds
    assets/hex/microcode-v2.<lang>.hex per language. Languages with no
    renderable translations are skipped. --coverage [--verbose] reports
    per-language translation coverage without building.
  • scripts/locstrings.mjs and scripts/tooltipgen.mjs regenerate the
    derived files; npm run loc:strings|loc:tooltips|loc:regen|loc:coverage|loc:hex|loc:verify.
  • Crowdin pipeline removed: scripts/lochex.mjs, the one-time catalog
    converter, and the node-fetch dependency are gone. The deployed web
    page's runtime strings (assets/strings/<lang>/tooltips.json) are now
    generated by locgen on every run from the catalogs, so the web surface
    tracks the same source of truth as the device builds -- including CJK
    languages, which localize on the web (browser fonts) even though they
    build no hex. Sample-name (N*) translations live in the catalogs and
    ship web-only, never occupying device flash.
  • .github/copilot-instructions.md updated to point contributors at the
    catalogs and ui.loc(...).

Verification

  • English build verified pixel-identical: per-site font audit (every path
    resolves the same bitmaps.font8 object as before) and simulator pass.
  • All 20 buildable language images build green with zero glyph drops; the
    four CJK languages skip themselves (no renderable translations).
  • Hardware-verified on device: fr, pl, and es-ES images, including accented
    glyph rendering.
  • Flash cost measured: English image unchanged; a Latin-language image adds
    roughly 1-3KB of table data. Remaining image headroom measured at ~29KB.
  • Web snapshots regenerated for all 24 languages and spot-checked against
    the legacy files; device tables and hex sizes verified unchanged by the
    web-surface work.

Release note

Parked as draft until ui-controls bump, pending microbit-apps/ui-controls#1

@humanapp

Copy link
Copy Markdown
Contributor Author

@thomasjball I committed the built per-locale built hex files, thinking this might be a convenient distribution method. Let me know if you'd prefer them excluded.

@humanapp

Copy link
Copy Markdown
Contributor Author

@thomasjball, I retired the Crowdin loc pipeline, in favor of the procedure outlined in locales/README.md ("Adding a new string"). Please let me know if that should have been kept and I'll put it back.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Pull request overview

This PR migrates MicroCode’s UI text and tooltip localization to the ui-core runtime end-to-end, replacing the legacy Crowdin-based pipeline with in-repo, source-string-keyed catalogs plus new generation/build scripts to produce per-language artifacts.

Changes:

  • Updates runtime UI code to resolve localized strings via ui.loc(...) and fonts via ui.locFont() (avoiding module-init-time font capture).
  • Introduces new localization tooling (locstrings.mjs, tooltipgen.mjs) and a committed placeholder loc.g.ts that is first in pxt.json load order.
  • Replaces/refreshes localization data sources (locales/*.json, locales/tooltips.json) and regenerates web tooltip snapshots under assets/strings/<lang>/tooltips.json.

Reviewed changes

Copilot reviewed 64 out of 85 changed files in this pull request and generated 1 comment.

Show a summary per file
File Description
styles.ts Removes eager font capture from a shared button style to allow runtime-selected localized defaults.
scripts/tooltipgen.mjs Adds generator for derived tooltips.ts from locales/tooltips.json.
scripts/locstrings.mjs Adds extractor to generate locales/en.json from ui.loc* call sites.
scripts/lochex.mjs Removes the legacy Crowdin fetch/build script.
screens/settings.ts Wraps settings UI strings with ui.loc(...) and switches title rendering to ui.locFont().
screens/home.ts Documents font constraints for the (non-localized) tagline rendering path.
screens/editor.ts Localizes literal button labels (e.g. “OK”), composes FocusLabel style, and aligns measurement with ui.locFont().
pxt.json Ensures loc.g.ts loads first via files ordering.
package.json Removes node-fetch and adds npm scripts for loc generation/coverage/verification.
package-lock.json Updates lockfile to reflect removed node-fetch dependency tree.
locales/tooltips.json Adds missing tooltip id entry (delete).
locales/README.md Documents the new catalog rules and contributor workflow.
locales/en.json Adds generated English catalog keys discovered from ui.loc(...) usage.
locales/de.json Adds German source-string-keyed translation catalog.
locales/ca.json Adds Catalan source-string-keyed translation catalog.
locales/cy.json Adds Welsh source-string-keyed translation catalog.
locales/eu.json Adds Basque source-string-keyed translation catalog.
locales/es-ES.json Adds Spanish (Spain) source-string-keyed translation catalog.
locales/es-MX.json Adds Spanish (Mexico) source-string-keyed translation catalog.
locales/fil.json Adds Filipino source-string-keyed translation catalog.
locales/fr.json Adds French source-string-keyed translation catalog.
locales/fr-CA.json Adds French (Canada) source-string-keyed translation catalog.
locales/hr.json Adds Croatian source-string-keyed translation catalog.
locales/hu.json Adds Hungarian source-string-keyed translation catalog.
locales/it.json Adds Italian source-string-keyed translation catalog.
locales/ja.json Adds Japanese source-string-keyed translation catalog (data retained even if device builds skip).
locales/ko.json Adds Korean source-string-keyed translation catalog (data retained even if device builds skip).
locales/nl.json Adds Dutch source-string-keyed translation catalog.
locales/pt-BR.json Adds Portuguese (Brazil) source-string-keyed translation catalog.
locales/pt-PT.json Adds Portuguese (Portugal) source-string-keyed translation catalog.
locales/ru.json Adds Russian source-string-keyed translation catalog.
locales/tr.json Adds Turkish source-string-keyed translation catalog.
locales/zh-CN.json Adds Chinese (Simplified) source-string-keyed translation catalog (data retained even if device builds skip).
locales/zh-HK.json Adds Chinese (Hong Kong) source-string-keyed translation catalog (data retained even if device builds skip).
loc.g.ts Adds committed placeholder for generated per-language translation table with required load ordering.
control-grid.ts Ensures localized title drawing uses ui.locFont() at render time.
assets/strings/en/tooltips.json Updates generated web tooltip snapshot (including delete and removing legacy SR_* entries).
assets/strings/de/tooltips.json Updates generated web tooltip snapshot for German.
assets/strings/ca/tooltips.json Updates generated web tooltip snapshot for Catalan.
assets/strings/fr/tooltips.json Updates generated web tooltip snapshot for French.
assets/strings/fr-CA/tooltips.json Updates generated web tooltip snapshot for French (Canada).
assets/strings/it/tooltips.json Updates generated web tooltip snapshot for Italian.
assets/strings/nl/tooltips.json Updates generated web tooltip snapshot for Dutch.
assets/strings/pt-BR/tooltips.json Updates generated web tooltip snapshot for Portuguese (Brazil).
assets/strings/ru/tooltips.json Updates generated web tooltip snapshot for Russian.
assets/strings/fil/tooltips.json Updates generated web tooltip snapshot for Filipino.
assets/strings/ja/tooltips.json Updates generated web tooltip snapshot for Japanese.
assets/strings/ko/tooltips.json Updates generated web tooltip snapshot for Korean.
assets/strings/zh-CN/tooltips.json Updates generated web tooltip snapshot for Chinese (Simplified).
assets/strings/zh-HK/tooltips.json Updates generated web tooltip snapshot for Chinese (Hong Kong).
.github/copilot-instructions.md Updates contributor guidance to reference locales/ catalogs and ui.loc(...).

Comment thread scripts/locstrings.mjs

@thomasjball thomasjball 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.

@humanapp - looks great - thanks for this major language facelift!

@humanapp
humanapp marked this pull request as ready for review July 23, 2026 02:58
@humanapp
humanapp merged commit dc455d3 into main Jul 23, 2026
1 check passed
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