Skip to content

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

Release notes: English in full, then Chinese in full (and the sheet reads both shapes)

LNPANDY9cfb8e10b0fc
diff --git a/docs/RELEASE-NOTES-GUIDE.md b/docs/RELEASE-NOTES-GUIDE.md
index bdd17825..ba1f3323 100644
--- a/docs/RELEASE-NOTES-GUIDE.md
+++ b/docs/RELEASE-NOTES-GUIDE.md
@@ -1,45 +1,77 @@
-# Release notes: both languages, every time
+# Release notes: English first, then Chinese
-Every release body is written in **Chinese first, then English**, in the same file, with the same
-structure. This exists because the fork's users are mostly Chinese while the upstream project and
-most contributors are not, and a release written in one language loses half of them.
+Every release body is written in **English first, then Chinese**, as two complete halves with a
+`---` between them. This exists because the fork's users are mostly Chinese while the upstream
+project and most contributors are not, and a release written in one language loses half of them.
+
+**Do not interleave the languages.** Earlier releases alternated one Chinese line and one English
+line, and the result was hard to read in both: a Chinese reader's eye had to skip every other line,
+and the two halves could not be compared. Each language is written as a complete document, in the
+same section order, and a reader picks one and reads straight through.
## The shape
```
-## 这一版做了什么 / What this release does
+## What this release does
+<one paragraph>
-**中文** — one paragraph: what changed for someone who already uses the app.
+## New (optional: only when there is new functionality)
+- …
-**English** — the same paragraph, not a summary of it.
+## Fixes
+- …
-## 修复 / Fixes
+## Known issues
+- …
+
+## Install
+- …
-- 中文条目。
-- English entry.
-- (同一件事两种语言写在相邻的两行,不分组、不重复编号)
+## Credits
+- …
-## 已知问题 / Known issues
+---
-- (同上)
+## 这一版做了什么
+<一段>
-## 安装 / Install
+## 新增 (可选)
+- …
-- **macOS**: 文件名 + 一句操作说明(两种语言各一行)
-- **Windows**: 发布与否、在哪里取(两种语言各一行)
+## 修复
+- …
+
+## 已知问题
+- …
+
+## 安装
+- …
+
+## 致谢
+- …
```
+The two halves use the **same headings in the same order** (the Chinese ones are the translations
+of the English ones), and the same number of items under each heading. Item 2 in English is item 2
+in Chinese; a reader comparing the two must not have to map lists.
+
Rules that matter more than the template:
-1. **Both languages say the same thing.** Not "a translation of the headline and a summary of the
- rest" — a user reading either language must learn everything the other one learns.
-2. **Never renumber or split by language.** Item 2 in Chinese is item 2 in English; a reader
- comparing two versions of the same release must not have to map lists.
-3. **Say what it does for the user, not what the commit did.** "游戏数据现在是一个文件,拷到手机上
+1. **English first.** It is the canonical text; the Chinese half is written from it.
+2. **Both halves say the same thing.** Not "a translation of the headline and a summary of the
+ rest" — a user reading either half must learn everything the other one learns.
+3. **Never split a section across the two halves.** All of Fixes is in one place, then all of
+ 修复 is in the other.
+4. **Say what it does for the user, not what the commit did.** "游戏数据现在是一个文件,拷到手机上
快得多" beats "switched romfs_arc.py to romfs_image.py" — and the English line says the same.
-4. **State what is NOT shipped.** If the Windows build is not in the release, both languages say so
- in the same place (a reader who only reads one must not conclude the other platform shipped).
-5. **Credit contributors by name in both languages**, with the PR number.
+5. **State what is NOT shipped.** If the Windows build is not in the release, both halves say so in
+ the same section (a reader who only reads one must not conclude the other platform shipped).
+6. **Credit contributors by name in both halves**, with the PR number.
+
+The app's own update sheet (`UpdateSheet.swift`) reads the body and shows one language: it splits on
+the `**中文**` / `**English**` markers if they are there, and otherwise picks the lines whose
+characters belong to the reader's language. A body in the shape above works with both paths, so
+changing the template means checking that sheet's tests too.
## Where the text comes from
diff --git a/frontend/Sources/NSPortBuilder/UpdateSheet.swift b/frontend/Sources/NSPortBuilder/UpdateSheet.swift
index d8a26190..efc7ad9e 100644
--- a/frontend/Sources/NSPortBuilder/UpdateSheet.swift
+++ b/frontend/Sources/NSPortBuilder/UpdateSheet.swift
@@ -73,57 +73,72 @@ struct UpdateSheet: View {
/// The release body's lines for one language.
///
- /// The notes are written to a fixed shape (docs/RELEASE-NOTES-GUIDE.md): a bilingual heading
- /// ("## 这一版做了什么 / What this release does"), then `**中文** …` and `**English** …` paragraphs,
- /// then a bullet list that interleaves the two languages one item at a time. So the language is
- /// known from the line's own marker, not from whether it happens to contain Chinese characters —
- /// the first version of this did that and gave an English reader the Chinese paragraph, because
- /// `**中文** …` contains both.
+ /// Two shapes are in the wild, both described in docs/RELEASE-NOTES-GUIDE.md:
+ ///
+ /// * **Current**: English written out in full, `---`, then Chinese in full. The `---` is the
+ /// split, so the two halves are read straight through and neither reader sees the other's text.
+ /// * **Older releases (0.4.7 and before)**: `**中文** …` and `**English** …` paragraphs with the
+ /// bullet lists interleaved one line each. Those are split on the markers.
+ ///
+ /// A body with neither is shown whole — splitting it by guesswork is how the first version gave
+ /// an English reader the Chinese paragraph (that line contains both scripts).
static func lines(_ notes: String, for lang: Lang) -> [String] {
+ // Shape 1: two halves around a `---` line.
+ let halves = notes.components(separatedBy: "\n---\n")
+ if halves.count == 2 {
+ let first = clean(halves[0]), second = clean(halves[1])
+ // The English half first, as the guide requires; pick by which half is which, not by order
+ // alone, so a body written the other way round still reads correctly.
+ let firstIsEnglish = !containsHan(first.joined())
+ let english = firstIsEnglish ? first : second
+ let chinese = firstIsEnglish ? second : first
+ if !english.isEmpty && !chinese.isEmpty { return lang == .zh ? chinese : english }
+ }
+
+ // Shape 2: `**中文**` / `**English**` markers.
var zh: [String] = [], en: [String] = []
- // Headings go to both lists, so "one list is empty" is not the test for a bilingual body —
- // a monolingual body with a heading fills both. Count the tagged and bulleted lines instead.
- var bilingual = 0
+ var marked = 0
for raw in notes.split(separator: "\n", omittingEmptySubsequences: false) {
var s = raw.trimmingCharacters(in: .whitespaces)
if s.isEmpty || s.hasPrefix("---") { continue }
- if s.hasPrefix("#") { // a heading: keep it once, in either list
+ if s.hasPrefix("#") {
while s.hasPrefix("#") { s.removeFirst() }
s = s.trimmingCharacters(in: .whitespaces)
if !s.isEmpty { zh.append(s); en.append(s) }
continue
}
- // `**中文** …` / `**English** …` — the marker decides, and it is removed from the text
if let r = s.range(of: "**中文**") {
- bilingual += 1
+ marked += 1
zh.append(s[r.upperBound...].replacingOccurrences(of: "**", with: "").trimmingCharacters(in: .whitespaces))
} else if let r = s.range(of: "**English**") {
- bilingual += 1
+ marked += 1
en.append(s[r.upperBound...].replacingOccurrences(of: "**", with: "").trimmingCharacters(in: .whitespaces))
} else {
- // A bullet or plain line: no marker, so it belongs to whichever language it is in.
- // Chinese text has Han characters; English does not. (A bullet naming a title in
- // Chinese would land in the Chinese list, which is the right place for it.)
s = s.replacingOccurrences(of: "**", with: "")
- if s.range(of: "\u{4e00}", options: []) != nil || s.unicodeScalars.contains(where: { (0x4e00...0x9fff).contains($0.value) }) {
- zh.append(s)
- } else { en.append(s) }
+ if containsHan(s) { zh.append(s) } else { en.append(s) }
}
}
- // A body with no language markers at all is shown whole: splitting it would silently drop
- // half of it, which is what the first version did to a plain English body.
- if bilingual == 0 || zh.isEmpty || en.isEmpty {
- var all: [String] = []
- for raw in notes.split(separator: "\n", omittingEmptySubsequences: false) {
- var s = raw.trimmingCharacters(in: .whitespaces)
- if s.isEmpty || s.hasPrefix("---") { continue }
- while s.hasPrefix("#") { s.removeFirst() }
- s = s.replacingOccurrences(of: "**中文**", with: "").replacingOccurrences(of: "**English**", with: "")
- s = s.replacingOccurrences(of: "**", with: "").trimmingCharacters(in: .whitespaces)
- if !s.isEmpty { all.append(s) }
- }
- return all
+ if marked > 0, !zh.isEmpty, !en.isEmpty { return lang == .zh ? zh : en }
+
+ // Neither shape: show it as it is.
+ return clean(notes)
+ }
+
+ /// One half of a body as display lines: heading marks and bold marks stripped, blanks dropped.
+ private static func clean(_ half: String) -> [String] {
+ half.split(separator: "\n", omittingEmptySubsequences: false).compactMap { raw in
+ var s = raw.trimmingCharacters(in: .whitespaces)
+ if s.isEmpty || s.hasPrefix("---") { return nil }
+ while s.hasPrefix("#") { s.removeFirst() }
+ s = s.replacingOccurrences(of: "**中文**", with: "")
+ .replacingOccurrences(of: "**English**", with: "")
+ .replacingOccurrences(of: "**", with: "")
+ .trimmingCharacters(in: .whitespaces)
+ return s.isEmpty ? nil : s
}
- return lang == .zh ? zh : en
+ }
+
+ private static func containsHan(_ s: String) -> Bool {
+ s.unicodeScalars.contains { (0x4e00...0x9fff).contains($0.value) }
}
}
diff --git a/frontend/Tests/NSPortBuilderTests/UpdateSheetTests.swift b/frontend/Tests/NSPortBuilderTests/UpdateSheetTests.swift
index 378be39a..6f8915e5 100644
--- a/frontend/Tests/NSPortBuilderTests/UpdateSheetTests.swift
+++ b/frontend/Tests/NSPortBuilderTests/UpdateSheetTests.swift
@@ -54,4 +54,61 @@ final class UpdateSheetTests: XCTestCase {
let bold = "**中文** 见 **NX2Apple** 的设置。"
XCTAssertEqual(UpdateSheet.lines(bold, for: .zh), ["见 NX2Apple 的设置。"])
}
+
+ // The format used from 0.4.8 on: English in full, `---`, Chinese in full.
+ private let twoHalves = """
+ ## What this release does
+
+ The launcher installs to a paired device.
+
+ ## Fixes
+
+ - Every rewrite crashed.
+
+ ---
+
+ ## 这一版做了什么
+
+ 启动器可以装到配对设备。
+
+ ## 修复
+
+ - 每一次重写都会崩。
+ """
+
+ func testTheTwoHalvesFormatGivesEachReaderItsOwnHalf() {
+ let en = UpdateSheet.lines(twoHalves, for: .en)
+ let zh = UpdateSheet.lines(twoHalves, for: .zh)
+ XCTAssertTrue(en.contains { $0.contains("installs to a paired device") })
+ XCTAssertFalse(en.contains { $0.contains("启动器可以装到配对设备") }, "English half leaked: \(en)")
+ XCTAssertTrue(zh.contains { $0.contains("启动器可以装到配对设备") })
+ XCTAssertFalse(zh.contains { $0.contains("installs to a paired device") }, "Chinese half leaked: \(zh)")
+ }
+
+ func testTheTwoHalvesKeepTheirOwnHeadings() {
+ let en = UpdateSheet.lines(twoHalves, for: .en)
+ let zh = UpdateSheet.lines(twoHalves, for: .zh)
+ XCTAssertTrue(en.contains("What this release does"))
+ XCTAssertTrue(en.contains("Fixes"))
+ XCTAssertFalse(en.contains("这一版做了什么"))
+ XCTAssertTrue(zh.contains("这一版做了什么"))
+ XCTAssertTrue(zh.contains("修复"))
+ XCTAssertFalse(zh.contains("What this release does"))
+ }
+
+ func testAHalvesBodyWrittenChineseFirstStillReadsCorrectly() {
+ let flipped = """
+ ## 这一版做了什么
+
+ 中文在前。
+
+ ---
+
+ ## What this release does
+
+ English second.
+ """
+ XCTAssertTrue(UpdateSheet.lines(flipped, for: .en).contains { $0.contains("English second") })
+ XCTAssertTrue(UpdateSheet.lines(flipped, for: .zh).contains { $0.contains("中文在前") })
+ }
}