Skip to content

Play your own Switch games on iPhone/iPad — one-click macOS app, no terminal. | 把 Switch 游戏装进 iPhone:图形界面一键构建,不用命令行。Bring your own game.

Build scripts and workflows carry the language files, docs say where texts live (#388)

v0lumehicce778ea285e
diff --git a/.github/labeler.yml b/.github/labeler.yml
index 7544b6e5..0f8857bb 100644
--- a/.github/labeler.yml
+++ b/.github/labeler.yml
@@ -3,7 +3,7 @@ launcher:
- any-glob-to-any-file: 'frontend/**'
windows:
- changed-files:
- - any-glob-to-any-file: 'frontend-qt/**'
+ - any-glob-to-any-file: ['frontend-qt/**', 'frontend/l10n/**']
ios:
- changed-files:
- any-glob-to-any-file: 'frontend-ios/**'
diff --git a/.github/workflows/build-mac-app.yml b/.github/workflows/build-mac-app.yml
index bd226de8..25933b39 100644
--- a/.github/workflows/build-mac-app.yml
+++ b/.github/workflows/build-mac-app.yml
@@ -301,6 +301,8 @@ jobs:
# The iPhone shell's Swift package: build_shell.sh links it by DM_SHELL_PACKAGE and the launcher passes this folder (the engine has
# none since #214). The step runs in frontend/, the package is one level up. No .build or .swiftpm.
rsync -a --exclude .build --exclude .swiftpm ../frontend-ios/ "$APP/Contents/Resources/frontend-ios/"
+ # The launcher's texts, one JSON file per language (#388): L10n reads Contents/Resources/l10n, not SwiftPM resources (this step builds the bundle by hand).
+ rsync -a l10n/ "$APP/Contents/Resources/l10n/"
V="${{ steps.ver.outputs.version }}"
cat > "$APP/Contents/Info.plist" <<PLIST
<?xml version="1.0" encoding="UTF-8"?>
@@ -346,6 +348,8 @@ jobs:
test -f "$E/scripts/build_ipa_from_nsp.py" && test -f "$E/dm/tools/romfs_image.py" && test -f "$E/dm/fork_patches.txt"
# The iPhone shell's package (DM_SHELL_PACKAGE): the project template links it and its AppIcon.icon.
test -f "NX2Apple.app/Contents/Resources/frontend-ios/Package.swift" && test -d "NX2Apple.app/Contents/Resources/frontend-ios/AppIcon.icon"
+ # The language files: every one is there and identical to the checkout's (check_bundle.sh also reads them as JSON).
+ diff -r l10n NX2Apple.app/Contents/Resources/l10n
test ! -e "$E/.git"
# The engine files are the zip asset's, byte for byte, and spirv-cross matches dmsh_chain.lock, so a shader build from the bundled engine starts.
tools/sign_engine_tree.sh --check "$E" "$RUNNER_TEMP/engine-tree"
diff --git a/.github/workflows/build-qt.yml b/.github/workflows/build-qt.yml
index 33b5f83e..2cd44b42 100644
--- a/.github/workflows/build-qt.yml
+++ b/.github/workflows/build-qt.yml
@@ -35,9 +35,6 @@ jobs:
# install produced a 591 MB bundle with the same exclusions in place.
python -m pip install PySide6-Essentials pyinstaller
- - name: Generate the localisation table
- run: python frontend-qt/gen_localization.py
-
# The build packages ride in the zip: the venv step then installs from disk (--no-index),
# so a fresh machine needs no PyPI round-trip for lz4/capstone/fonttools/nsz. The runner's
# Python is the version these wheels target (3.12), matching the interpreter the app
@@ -52,7 +49,8 @@ jobs:
shell: bash
run: |
# Manrope (the Mac launcher's typeface, SIL OFL 1.1) goes into the bundle's fonts folder
- # with its licence; style.load_font() looks for it there.
+ # with its licence; style.load_font() looks for it there. The language files (frontend/l10n, the ones the
+ # Mac launcher reads too) go into the bundle's l10n folder; nspb_qt/l10n.py looks for them there.
PATHSEP=';'
# --windowed: no console window. --name: the exe/bundle name.
# --collect-all PySide6 copies the whole PySide6 package and OVERRIDES
@@ -117,6 +115,7 @@ jobs:
--exclude-module PySide6.QtGraphsWidgets \
--add-data "../frontend/fonts/Manrope.ttf${PATHSEP}fonts" \
--add-data "../frontend/fonts/Manrope-OFL.txt${PATHSEP}fonts" \
+ --add-data "../frontend/l10n${PATHSEP}l10n" \
--paths . \
run_gui.py
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index 7dcd78ed..d787c918 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -285,14 +285,6 @@ jobs:
run: python tools/engine.py sync
- name: Tests
run: python -m unittest discover -s frontend-qt/tests -v
- # The Qt table is generated from the SwiftUI one and says so at its top. A string added to
- # Localization.swift without regenerating it left 18 keys missing here for a day (a source run
- # of the Qt app shows those as raw keys), so the regeneration is the check: any difference
- # means the committed table is stale.
- - name: The Qt language table matches Localization.swift
- run: |
- python frontend-qt/gen_localization.py
- git diff --exit-code -- frontend-qt/nspb_qt/localization.py
triage-scripts:
name: Triage script tests (.github/scripts)
diff --git a/AGENTS.md b/AGENTS.md
index a30d9cdf..c7631098 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -12,6 +12,6 @@ This is the fork's guide. The engine has its own, upstream's: [engine/AGENTS.md]
- **Issues and pull requests.** Follow [CONTRIBUTING.md](CONTRIBUTING.md), section "For AI agents and other tools", and the forms and the PR template in `.github/`. Fix or feature: every fix goes through a PR and merges when CI is green, unless a maintainer's "changes requested" review is unanswered (a plain review comment does not block, and @LNPANDY decides only when the maintainers disagree), a maintainer's own feature after 48 hours (a feature from outside never merges by waiting, a maintainer has to agree, try the app and review the code), a patch is renumbered by whoever merges it, releases and version bumps are the owner's ([RELEASING.md](RELEASING.md): a release candidate tag first, the final tag on its commit). `tools/try-pr <PR number|main|tag>` opens the app CI built. `tools/try-local` builds the app from your checkout without CI and opens it (engine tree, launcher, bundled tools, ad-hoc signed, version `<appVersion>-local`). The first run builds the bundled tools, which it caches (minutes), a later one takes about the time of `swift build`. It is not a release and cannot sign: an rc tag still needs CI and the owner's key. Never attach or commit keys, game files or data extracted from a game.
- **Merging with admin rights.** An admin merge never goes over a red check. That holds even when @LNPANDY overrides an objection. If a re-review is slow, the other maintainer pings the reviewer and does not merge with admin rights.
- **Mac launcher layers.** `frontend/` is four SwiftPM targets (`NXCore`, `NXModel`, `NXLauncher`, `NX2Apple`) and the compiler enforces which may import which. Read [frontend/ARCHITECTURE.md](frontend/ARCHITECTURE.md) before you add a file to `frontend/Sources`. It says where a new feature goes. `BuildModel` is gone: the stores are in `NXModel` and `LauncherStores` only wires them. No Swift file there is above 800 lines (`SourceSizeTests`), and the larger ones may only shrink.
-- **Checks.** `cd frontend && swift build && swift test` for the Mac launcher (its tests read `engine/`, so sync first), `python3 -m unittest discover -s frontend-qt/tests` for the Qt front end (and `python3 frontend-qt/gen_localization.py` leaves `frontend-qt/nspb_qt/localization.py` unchanged), `python3 -m unittest discover tools/tests` for the tools. The engine's own tests run in `engine/` as `tests.yml` does. The pre-commit hook runs `python3 tools/engine.py check` when `patches/` or `.upstream-ref` is staged. The pre-push hook runs the checks above for the files the push changes, `tools/githooks.py` has the list. Fix the failure, do not bypass the hook.
-- **Language and text.** Everything is in English except the Chinese pages (`*.zh-CN.md`) and the launcher's strings. No semicolons in UI strings, READMEs and docs.
+- **Checks.** `cd frontend && swift build && swift test` for the Mac launcher (its tests read `engine/`, so sync first), `python3 -m unittest discover -s frontend-qt/tests` for the Qt front end, `python3 -m unittest discover tools/tests` for the tools. The engine's own tests run in `engine/` as `tests.yml` does. The pre-commit hook runs `python3 tools/engine.py check` when `patches/` or `.upstream-ref` is staged. The pre-push hook runs the checks above for the files the push changes, `tools/githooks.py` has the list. Fix the failure, do not bypass the hook.
+- **Language and text.** Everything is in English except the Chinese pages (`*.zh-CN.md`) and the launcher's strings. No semicolons in UI strings, READMEs and docs. The launcher's strings are not in Swift or Python code. They are one JSON file per language in `frontend/l10n/`, read by the Mac launcher and the Windows launcher. A new string is a line in `en.json` and `zh.json` (English and Chinese have every key, the other languages may miss one and then show English). The files go into the apps by the build workflows, see `frontend/README.md`, section "Language".
- **Release notes.** They follow `.github/release_notes_template.md`, English first, then Chinese, no emojis.
diff --git a/frontend/ARCHITECTURE.md b/frontend/ARCHITECTURE.md
index 310e3711..2f00395c 100644
--- a/frontend/ARCHITECTURE.md
+++ b/frontend/ARCHITECTURE.md
@@ -16,7 +16,7 @@ The plan and the steps are in [LNPANDY/NX2Apple#387](https://github.com/LNPANDY/
Step 1 of #387 made the targets and moved the files that already fit. Step 2 moved the language out of `BuildModel` into the `Localizer` store. Step 3 moved the build log into the `BuildLog` store. Step 4 moved the pure logic into `NXCore`. Step 5 added the first services. Step 6 added the first store, `AppUpdateStore`, the reference for the others. Step 7 moved the rest one store per PR: the repository, the engine sync, the dependencies, the devices, then the build. `BuildModel` is gone. Step 8 split `BuilderView` into one view per card and deleted `ContentView.swift`. The window's root view is `LauncherView`.
- `LauncherStores` (app target, `LauncherStores.swift`) is the wiring and nothing else: it creates the services and the stores, connects them and hands them to the views. Every store is a `let`. It holds no logic and no `@Published` state. The views take the stores they show as parameters.
-- `NXCore` holds the value types and static functions that need only Foundation: app and engine update parsing, `Localization.swift`, the release notes, the device and signing tools, the cloud folder and saves migration, the bundled tools, input staging, the build target and the pipe reader. Step 4 added four types: `TitleID` (parse a title ID from a file name, its owner, the update version, the build key), `GameInputs` (classify files into the four rows, row mismatch, allowed file types), `BuildProgress` (stage lines, progress details, durations, the steps of Xcode and the install, failure info) and `Toolchain` (probing Python, the venv, dotnet and Xcode, and the dependency rows `Dep`). `Stage` and `StepState` moved with `BuildProgress`. Step 5 added the first services (step 6 added `ReleaseSource`, see below): `ProcessRunner` (a protocol, with `SystemProcessRunner` as the real one), `ProcessGroups` (the process groups that Stop and quitting end) and `GitCheckout` (a protocol, with `SystemGitCheckout`, plus `GitRules` for the decisions that need no git). `ProcessRunner` is where a build process starts: `capture` runs to the end and keeps the output, `stream` hands out lines, `start` returns at once and can lead a process group. `LauncherStores` creates a runner and a checkout and hands them to the stores that use them: the clone, fetch, pull and adoption of a ZIP copy (`RepoStore`), the build run, the tools of a stage, the archive step and `openOnDevice` (`BuildStore`). `Toolchain`, `Diagnostics`, `OlderTools`, `Uninstall`, `EngineLayout.runSync` and the update staging take a runner or a checkout as a parameter with the real one as default. Tests pass in a fake. These still start a `Process` themselves and move with the step that owns them: `EngineInstaller` (ditto, in `NXCore` since the engine sync store), the administrator prompt in `LiveOnboardingDriver` and the game start in `LiveConsoleDriver`. The tools of the device store (`DeviceTools`, `AppSignature`, `DeviceControl`, `ShellInstaller`) moved onto `ProcessRunner` with the device store, see below. What reads `OnboardingDefaults` (`needsIOSPlatform`, the platform choice that asks for a new dependency check) stays in the app target, in `LauncherStores`, because the guided setup owns those keys.
+- `NXCore` holds the value types and static functions that need only Foundation: app and engine update parsing, the language choice and lookup (`Localization.swift`, with `LocalizationFiles.swift` reading the texts from `frontend/l10n/*.json`), the release notes, the device and signing tools, the cloud folder and saves migration, the bundled tools, input staging, the build target and the pipe reader. Step 4 added four types: `TitleID` (parse a title ID from a file name, its owner, the update version, the build key), `GameInputs` (classify files into the four rows, row mismatch, allowed file types), `BuildProgress` (stage lines, progress details, durations, the steps of Xcode and the install, failure info) and `Toolchain` (probing Python, the venv, dotnet and Xcode, and the dependency rows `Dep`). `Stage` and `StepState` moved with `BuildProgress`. Step 5 added the first services (step 6 added `ReleaseSource`, see below): `ProcessRunner` (a protocol, with `SystemProcessRunner` as the real one), `ProcessGroups` (the process groups that Stop and quitting end) and `GitCheckout` (a protocol, with `SystemGitCheckout`, plus `GitRules` for the decisions that need no git). `ProcessRunner` is where a build process starts: `capture` runs to the end and keeps the output, `stream` hands out lines, `start` returns at once and can lead a process group. `LauncherStores` creates a runner and a checkout and hands them to the stores that use them: the clone, fetch, pull and adoption of a ZIP copy (`RepoStore`), the build run, the tools of a stage, the archive step and `openOnDevice` (`BuildStore`). `Toolchain`, `Diagnostics`, `OlderTools`, `Uninstall`, `EngineLayout.runSync` and the update staging take a runner or a checkout as a parameter with the real one as default. Tests pass in a fake. These still start a `Process` themselves and move with the step that owns them: `EngineInstaller` (ditto, in `NXCore` since the engine sync store), the administrator prompt in `LiveOnboardingDriver` and the game start in `LiveConsoleDriver`. The tools of the device store (`DeviceTools`, `AppSignature`, `DeviceControl`, `ShellInstaller`) moved onto `ProcessRunner` with the device store, see below. What reads `OnboardingDefaults` (`needsIOSPlatform`, the platform choice that asks for a new dependency check) stays in the app target, in `LauncherStores`, because the guided setup owns those keys.
- Step 6 moved the self-update out of `BuildModel`. `AppUpdate` (`NXCore`) now also holds the release parsing (`release(fromJSON:)`, `check(latest:current:)`), the version compare (`isNewer`), the asset names, the staging of a download (`stage`, `StageFailure`) and the install, which clears the quarantine flag through a `ProcessRunner`. `ReleaseSource` is the second service (a protocol, with `GitHubReleases` as the real one): the latest release and the download. `Uninstall` moved to `NXCore` too, because the store holds its plan. `AppUpdate.relaunch` still starts its detached shell itself, and the store gets it as a closure.
- `NXCoreTests` tests `NXCore` alone. It links no other target, so these tests run without SwiftUI. New tests of pure logic go there.
- `NXModel` holds `Localizer`: `lang` and `t()`. `LauncherStores` creates one, and `LauncherView` hands it to every view as an environment object. A view that shows text declares `@EnvironmentObject var loc: Localizer` and calls `loc.t(...)`. A language change redraws these views and nothing else.
diff --git a/frontend/README.md b/frontend/README.md
index aa2f5f0d..12dcccfe 100644
--- a/frontend/README.md
+++ b/frontend/README.md
@@ -303,12 +303,21 @@ nothing changes: Homebrew's tools, a system Python or the launcher's venv. To tr
The interface follows the system language at every launch: any Chinese variant
(Simplified, Traditional, Hong Kong, Taiwan) gets Chinese, Swedish gets Swedish, German gets
German, French gets French, and every other language gets English. Settings > Language overrides
-that. Strings live in `Sources/NXCore/Localization.swift`: the table holds Chinese and
-English, and Swedish (`sv`), German (`de`) and French (`fr`) are overlays below it. A string added
-to the table needs its German and French entries, and `GermanLocalizationTests` and
-`FrenchLocalizationTests` fail until it has them (they also check that the format placeholders
-match the English text). Regenerate the Qt table after editing it with
-`python3 frontend-qt/gen_localization.py` from the repository root.
+that. The texts are not in Swift. Every language is one JSON file in `l10n/` (`en.json`, `zh.json`,
+`sv.json`, `de.json`, `fr.json`): a flat object with the keys sorted, UTF-8 text without escapes, and a
+`_language` entry that holds the language's own name and the locale prefixes that select it.
+`Sources/NXCore/Localization.swift` keeps only the language choice and the lookup, and
+`LocalizationFiles.swift` reads the files once, at the first lookup. A new string is a line in
+`l10n/en.json` and one in `l10n/zh.json`: English and Chinese have every key. Swedish, German and French
+may miss a key and then show the English text, and `GermanLocalizationTests` and
+`FrenchLocalizationTests` check the entries they have (placeholders match the English text). The Windows
+launcher reads the same files, so one edit serves both.
+
+The app finds the files in `Contents/Resources/l10n` (`build-mac-app.yml` and `tools/try-local` copy the
+folder there, the same way as the engine and the bundled tools, not as SwiftPM resources). `swift run` finds
+`frontend/l10n` by walking up from the executable, and `swift test` takes it from the source path.
+`NX_L10N_DIR` names another folder for a try-out. A missing or broken file does not stop the app: the
+lookup shows the English text, then the key, and one line goes to standard error.
## Verification
diff --git a/frontend/tools/check_bundle.sh b/frontend/tools/check_bundle.sh
index e5d735ba..95b236db 100755
--- a/frontend/tools/check_bundle.sh
+++ b/frontend/tools/check_bundle.sh
@@ -39,6 +39,11 @@ done < <(find "$RES/tools" "$RES/python" -type f -print0)
# the icon: Assets.car (macOS 26 and later) and AppIcon.icns (13 to 25), and the two Info.plist keys that point at them
if [ -d "$APP/Contents" ]; then
for f in Assets.car AppIcon.icns; do [ -s "$RES/$f" ] && ok "$f is in the bundle" || bad "$f is missing from Resources"; done
+ # the launcher's texts (#388): Contents/Resources/l10n, one JSON file per language, each a JSON object with an English text of its own
+ for c in en zh sv de fr; do
+ v=$(clean "$PY" -I -c "import json, sys; d = json.load(open(sys.argv[1], encoding='utf-8')); assert isinstance(d, dict) and len(d) > 1 and '_language' in d" "$RES/l10n/$c.json" 2>&1) \
+ && ok "l10n/$c.json is in the bundle and reads as JSON" || bad "l10n/$c.json is missing or broken: $v"
+ done
for k in CFBundleIconName CFBundleIconFile; do
v=$(/usr/libexec/PlistBuddy -c "Print :$k" "$APP/Contents/Info.plist" 2>&1)
[ "$v" = AppIcon ] && ok "Info.plist $k = $v" || bad "Info.plist $k is '$v', not AppIcon"
diff --git a/tools/githooks.py b/tools/githooks.py
index 75df5bbf..ab7599cf 100755
--- a/tools/githooks.py
+++ b/tools/githooks.py
@@ -23,8 +23,7 @@ Check = namedtuple('Check', 'name prefixes command cwd sync')
CHECKS = (
Check('patch queue', ('patches/', '.upstream-ref'), 'python3 tools/engine.py check', '.', False),
- Check('Qt front end', ('frontend-qt/',), 'python3 -m unittest discover -s frontend-qt/tests'
- ' && python3 frontend-qt/gen_localization.py && git diff --exit-code HEAD -- frontend-qt/nspb_qt/localization.py', '.', True),
+ Check('Qt front end', ('frontend-qt/', 'frontend/l10n/'), 'python3 -m unittest discover -s frontend-qt/tests', '.', True),
Check('tools', ('tools/',), 'python3 -m unittest discover tools/tests', '.', True),
Check('triage scripts', ('.github/scripts/',), 'python3 -m unittest discover -s .github/scripts/tests', '.', True),
Check('Mac launcher (slow)', ('frontend/',), 'swift build && swift test', 'frontend', True),
diff --git a/tools/tests/test_githooks.py b/tools/tests/test_githooks.py
index 85567f0b..5600f8c9 100644
--- a/tools/tests/test_githooks.py
+++ b/tools/tests/test_githooks.py
@@ -65,8 +65,6 @@ class ChecksFor(unittest.TestCase):
cmds = {c.name: c.command for c in H.CHECKS}
self.assertEqual(cmds['tools'], 'python3 -m unittest discover tools/tests')
self.assertIn('python3 -m unittest discover -s frontend-qt/tests', cmds['Qt front end'])
- self.assertIn('python3 frontend-qt/gen_localization.py', cmds['Qt front end'])
- self.assertIn('git diff --exit-code HEAD -- frontend-qt/nspb_qt/localization.py', cmds['Qt front end'])
self.assertEqual(cmds['triage scripts'], 'python3 -m unittest discover -s .github/scripts/tests')
self.assertEqual(cmds['Mac launcher (slow)'], 'swift build && swift test')
diff --git a/tools/try-local b/tools/try-local
index 153bfc9e..4044d785 100755
--- a/tools/try-local
+++ b/tools/try-local
@@ -139,6 +139,7 @@ ditto "$tools_cache/res/python" "$app/Contents/Resources/python"
ditto "$work/engine-tree" "$app/Contents/Resources/engine"
frontend/tools/sign_engine_tree.sh "$app/Contents/Resources/engine" "$work/engine-tree"
rsync -a --exclude .build --exclude .swiftpm frontend-ios/ "$app/Contents/Resources/frontend-ios/"
+rsync -a frontend/l10n/ "$app/Contents/Resources/l10n/"
cat > "$app/Contents/Info.plist" <<PLIST
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
@@ -173,6 +174,7 @@ cmp "$E/.engine-id" "$work/engine-tree/.engine-id"
cmp "$E/.upstream-ref" .upstream-ref
test -f "$E/scripts/build_ipa_from_nsp.py" && test -f "$E/dm/tools/romfs_image.py" && test -f "$E/dm/fork_patches.txt"
test -f "$app/Contents/Resources/frontend-ios/Package.swift" && test -d "$app/Contents/Resources/frontend-ios/AppIcon.icon"
+diff -r frontend/l10n "$app/Contents/Resources/l10n"
test ! -e "$E/.git"
frontend/tools/sign_engine_tree.sh --check "$E" "$work/engine-tree"
done_step