Learn: make tutorial copy layout-agnostic - #111
Merged
Conversation
JumpLink
force-pushed
the
fix/108-tutorial-layout-agnostic
branch
from
June 9, 2026 19:14
69d155c to
bf0fdba
Compare
JumpLink
marked this pull request as ready for review
June 9, 2026 19:21
The previous tutorial referenced control names that don't exist in the GNOME and Android UIs: - It said "Debugger" everywhere, but the tab in both apps is labeled "Debug" (issue #108 explicitly flagged this). - "monitor in the debugger" / "memory monitor" were generic, while the actual section in GNOME and Android is the "Hex Monitor". - The instructions for the addressing-modes example told users to enter values into "Start" and "Length" fields, which only exist in the (separate) Web app — GNOME and Android use a memory-region dropdown instead. - The "Our first program" and stepping copy still described the portrait FAB layout ("button in the top right", "click it again to run", "dropdown menu", "the button will switch to step mode"), which is wrong on desktop / wide layouts. Refer to actions by name (Assemble / Run / Step / Reset) and reference the visible UI parts ("Debug" view, "Hex Monitor", "Hexdump"). Replace the Start/Length example with a memory-region pick that matches the actual dropdown options. Result is correct for both GNOME layouts and for Android, without any portrait/desktop assumption. Fixes #108
The Learn: commit replaced four+ tutorial sentences that referenced
non-existent UI elements ("Debugger" tab, "Start"/"Length" inputs,
generic "monitor"). Regenerate .pot, then update the 15 .po files so
each language uses its own translation of the actual UI labels:
Debug view -> reuses each language's existing "Debug" tab label
Hex Monitor -> reuses each language's existing "Hex Monitor" label
Hexdump -> reuses each language's existing "Hexdump" label
Assemble / Run / Step / Reset / Copy
-> reuse each language's existing button labels
Voice/formality is preserved per language (e.g. German "du", French
"vous"). HTML tags, 6502 opcodes, registers, and hex literals are kept
verbatim.
Regenerate the Android i18n JSON files and the metainfo.xml (which
also picks up the previously-missing Hebrew strings) as side effects
of the translations build.
For #108
`cp -r ../translations/dist/locale ./data/locale` only behaves
correctly on the first build. On every subsequent run `./data/locale`
already exists, so cp copies the source dir into it and creates
`./data/locale/locale/{lang}/LC_MESSAGES/*.mo`. The runtime still
reads the old `./data/locale/{lang}/LC_MESSAGES/*.mo` from the first
build and never picks up new translations until `yarn clear:locales`
is run by hand.
Remove the destination before copying so each rebuild reflects the
current state of `../translations/dist/locale`.
JumpLink
force-pushed
the
fix/108-tutorial-layout-agnostic
branch
from
June 9, 2026 19:23
6e88c4c to
269178b
Compare
The first group on the Debug tab was titled "Settings", which made users opening the tab in desktop mode (where the debug panel sits below the game console) wonder whether they were looking at the debugger or at some app-wide settings page (issue #108, comment). Rename the group to "Debug Settings" so its purpose is obvious without context from the tutorial. For #108
Companion to the Gnome: rename commit. Each language uses its own compound of the existing "Debug" tab translation + "Settings" word (e.g. German "Debug-Einstellungen", Japanese デバッグ設定, Chinese 调试设置). Regenerate .pot, .mo, and the Android JSON files. For #108
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #108.
The tutorial text in
packages/learn/tutorial.mdxdescribed the portrait single-button (FAB) layout, which is wrong in the desktop layout (separate toolbar buttons + always-visible debugger panel). Issue title nailed it: the copy mixes both modes.Changes (4 spots, layout-agnostic)
Refers to actions by name instead of positions/interaction mechanics, so it's correct for both GNOME layouts, Web and Android.
Notes
tutorial.mdx). These 4 sentences are gettext msgids, so they'll need re-translation in ~15 languages — left to the normal Weblate flow, no.po/.potchurn in this PR.