0 Fork 0

Files

T

AAA cdd503a98d feat: improve feedback and App lifecycle reliability (#404 )

Waiting feedback and tooltips now share consistent presentation lifecycles, while App shutdown and native-media operation failures stay within their owning session or output. This phase also consolidates the project standards and publishes searchable English/Chinese reader documentation alongside the homepage.

Validation: repository hygiene and Markdown links; TypeScript, 971 Web tests and production build; website/documentation build; Go tests, vet and Windows/Linux builds with Windows capture checks; desktop/mobile UI and documentation review. Linux race, container and three-platform packaging checks run in the release pipeline. Physical macOS/Linux capture and broader network coverage remain outside this acceptance.

The owner approved v1.4.0 publication. Existing empty-source, Windows URL-handler and public-invitation timeout reports remain tracked; this release makes no claim to resolve those device/network reports. The Windows capture-border request is next-phase work.

## Release notes

### 中文

这是一次以稳定性和交互一致性为重点的功能更新。等待与提示更有反馈，App 启动、原生分享和连接恢复的边界处理得到改善，使用与部署指南也有了统一的文档中心。

#### 新增与改进

- 欢迎语、等待短句和六类可轮换的标签页标题共用一致的显示规则。等待短句从一开始就出现，并在停留时轮换；明确的错误与操作提示保持固定。
- 房间准入等漫画采用更克制的小人物与循环动效。改进 tooltip 的定位与指向，减少对播放器的遮挡；状态、图标和文案保持相同含义。
- 新增中英文文档中心，提供搜索、手机目录、使用教程、问题排查与自部署指南。官网 FAQ 聚焦开始使用前的问题，详细排查统一进入文档中心。

#### 修复

- 使用 `--local` 启动不再清空已保存的 Piik 站点地址。
- 打开系统浏览器不再阻塞 App 的退出流程；改进临时公网邀请、终端和诊断导出在关闭时的清理及错误反馈。
- 单条原生媒体连接的操作失败不再被误判为整个会话的协议错误；重复停止分享保持幂等。
- 修复连接替换、转发停止和异常退出时的部分资源清理问题，避免迟到结果影响当前连接。
- Windows 原生采集中，单个输出的编码错误只结束对应输出；共享采集源本身的错误仍会结束分享。

#### 升级与已知边界

本次保持现有协议版本与配置格式。更新 App 或自托管 Server 后，重新打开页面即可使用对应的新界面。

个别设备的空窗口列表、Windows 浏览器启动异常，以及 Linux 编码输出的故障隔离仍在跟进。macOS/Linux 的物理采集和更广泛的公网网络场景仍需实机验证；本次不宣称这些问题已经解决，也不承诺所有网络都能直连。

### English

This feature update focuses on stability and consistent feedback. Waiting states are easier to follow, App startup and native sharing handle several failure cases more reliably, and the new documentation center brings usage and deployment guides together.

#### New and improved

- Welcome lines, waiting captions and six groups of rotating tab titles follow one presentation lifecycle. Waiting captions appear immediately and rotate while visible; actionable errors and instructions remain fixed.
- Room-admission comics use restrained characters and looping motion. Tooltips point more accurately to their controls and interfere less with the player, with consistent meanings across illustrations, icons and copy.
- A new English/Chinese documentation center includes search, mobile navigation, usage guides, troubleshooting and self-hosting. The homepage FAQ covers questions before getting started and links to the documentation for detailed help.

#### Fixes

- Starting with `--local` no longer clears a saved Piik site address.
- Opening the system browser no longer blocks App shutdown. Temporary public invitations, the terminal and diagnostic exports handle cleanup and exit errors more consistently.
- An operation failure on one native media connection no longer becomes a protocol failure for the entire session. Repeated stop-sharing requests are safe.
- Fixed cleanup cases during connection replacement, relay shutdown and unexpected exits, preventing late results from affecting the current connection.
- On Windows, an encoder failure for one native output stops that output only. A failure of the shared capture source still ends sharing.

#### Updating and known limits

Protocol versions and configuration formats are unchanged. After updating the App or your self-hosted Server, reopen the page to use its updated interface.

Empty source lists on some devices, Windows browser-launch failures and Linux output-failure isolation remain under investigation. Physical macOS/Linux capture and broader public-network coverage still need device testing; this update does not claim to resolve those cases or guarantee a direct connection on every network.

2026-09-16 13:13:06 +08:00

12 KiB

Raw Permalink Blame History

Help translate Piik

中文 · Contributing

Piik currently includes Simplified Chinese and English. You can improve a label, proofread a guide, or contribute another language. Translations are reviewed through GitHub issues and pull requests.

For a wording suggestion, open an issue with the language, page or control, current text, proposed text and a brief reason. A screenshot or the steps to reach the text help establish context. Remove private invitations, passwords and personal content from screenshots. A wording suggestion does not require a development environment.

Make your first correction

Try the affected screen and read the nearby controls. Check both existing languages when helpful; the terminology and voice guide owns names and writing style.
Fork Piik and work on a branch from current main, following Contributing. Small text edits can also be proposed through GitHub's file editor.
Find the text in the files below. In a locale file, change the string value after the colon. Keep the key and its placeholders. Search the key in the source to see where it appears; for example:
```
rg -n -F 'host.title' src/client
```
Preview the affected screen and run the relevant checks. For a typo in one language, edit that language. If the underlying meaning changes, update the corresponding messages in every registered language.
Open a PR to main. Explain the wording problem, the language and surfaces changed, and what you checked. Mention anything you could not preview; maintainers can help with technical validation. PR format and publication follow Contributing.

Find the right text

Surface	Editable source
App launcher and shared Browser/App UI, including tooltips and accessible labels	English, Chinese
Welcome lines, waiting captions and changing browser-tab titles	The `enPlayful` / `zhPlayful` pools and title-frame catalogs in those same files; website welcome lines reuse these pools
Website	Page markup and interactive labels; text is paired by `en` and `zh-CN`
Introduction film	Film sources; captions, artwork and playback labels have their own bilingual text
App console window	`consoleCopy` in console.go; entries are ordered English, Chinese, visual; retain the third slot even when empty
README and entry guides	README pair, documentation home, getting started, troubleshooting and self-hosting, each with a `.zh-CN.md` counterpart

The App and Server serve the same web UI. Edit source files; build output and release packages are generated. Translating an App message does not also translate a website caption. Update related instructions when an action name changes. Technical references keep one shared version; see documentation ownership.

Language catalogs are bundled with the web assets; a new language also needs the registry import described below. Rebuild and publish the App or Server that serves the affected UI after an edit. Installed packages do not load external language files. When the App connects to a remote site, that site serves its UI, so updating the site's web translations does not require reinstalling the App. The website has its own build and deployment workflow. The documentation website renders those same Markdown sources; editing a guide updates its web page on the next website publication. Its navigation and search labels live in site/docs/. Use the website preview to check the generated page as well as GitHub's Markdown view.

Preserve meaning and syntax

Write naturally for the target audience. Use the shared glossary for role and password names. Introductions may be light; actions, errors and deployment steps must be clear. Preserve the conditions on performance, platform and connection claims. A cultural reference should still make sense to someone unfamiliar with it. Machine-assisted drafts need proofreading by someone who understands the language and the screen; raise unclear source text in the PR instead of guessing.

Locale files are TypeScript objects. These are existing examples:

// en.ts
"host.title": "{name}'s screen",
// zh.ts
"host.title": "{name} 的屏幕",

host.title is the lookup key; {name} is supplied by the application. Move the placeholder to fit the sentence, preserving its spelling, braces and number of occurrences. The current formatter substitutes each supplied variable once; repeating {name} would leave the second occurrence visible. It accepts plain strings, not HTML or ICU plural expressions. If a language needs plural forms or different sentence composition, describe the actual case so the caller and formatter can be changed together.

Keep quotes, escapes and commas valid. Preserve commands, config keys, URLs, download filenames and format markers such as %s in Go console text. Translate link labels and image descriptions; repair internal anchors when translating Markdown headings. Keep legal license text and third-party notices intact.

Add a language

Search existing issues and PRs for the language first. For a larger translation, start an issue with its language tag, intended coverage and any terminology or layout questions, so contributors can coordinate work and review.

Copy src/client/locales/en.ts to a file such as fr.ts. Translate the messages and title labels, write natural playful entries, and rename the three exports. Retain Record<CopyKey, string>, TitleFrameCatalog and PlayfulCatalog from zh.ts. Chinese currently defines the key set; either existing language can provide context. Complete all keys rather than spreading an English catalog over missing translations.
Import the exports in locales/index.ts and add one registry entry. For example, after translating the catalogs:
```
fr: { name: "Français", short: "FR", tag: "fr", copy: fr,
  titleFrames: frTitleFrames, playful: frPlayful },
```
Use an ASCII locale filename/key, the language's own name in name, a compact button label in short, and a matching language tag in tag. Keep the short label recognizable in one to three characters, such as 中, EN or FR; distinguish regional/script variants when they coexist. The registry supplies the language controls, document language, saved selection and App launch handoff. Chinese, English and visual mode retain their direct buttons; additional languages share one dropdown slot after visual mode. The selected extra language's short label appears on that slot, with its full name in the menu. Initial selection matches a registered tag or key, then its base language; unregistered languages use English. A saved choice takes precedence. The shared system-language policy also covers Chinese script and region variants across App, Server UI and website.
Check complete screens and the launch flow. New UI languages use English in the App console until its own translation is added. Console additions also require updating the launcher and loopback accepted-language checks together; use the App module map.
State coverage in the PR. Website, film and documentation translations can be contributed separately; their existing language controls must be updated when adding a language there. For right-to-left scripts, include text direction and layout verification; a translated catalog alone does not establish RTL support.

Pure-visual mode is an optional presentation, not another language to translate. The small visual scenes are shared with text modes; translate their labels and explanations in the normal catalog. Keep the visual option available.

Playful copy

Each language owns its welcome and waiting arrays, and each playful title has a fixed label plus a variations array. Add or remove entries in that language without matching another language's count, order or references. An empty array omits the decoration; one entry stays static. Operational keys and title labels still require complete translations. Errors, pauses, endings, required actions and slogans stay fixed.

Welcome entries carry text and two symbols, chosen from the existing icon vocabulary to express that sentence in the visual cipher. For example:

{ text: "Your seat is right here.", symbols: ["couch", "heart"] },

Waiting entries are plain strings such as "Pull up a comfy chair.". Keep them brief and natural in context. Avoid temporary trends, literal borrowed dialogue and statements that invent progress, success or remaining time.

All these surfaces show a line immediately and share the playful-copy lifecycle. Keep timing in that owner. Preview welcome text and its cipher at /__tooltip-preview; use /__status-preview for waiting captions and titles. Check both narrow windows and language changes. The website's build picks up welcome edits automatically; its other copy remains separate.

Preview and check

Use the Node/npm versions and local setup in Run from source. For UI catalog edits, run from the repository root:

npm ci
npm run typecheck
npm test -- tests/copy.test.ts

Type checking catches missing keys. The copy tests check registered catalogs for empty text and mismatched placeholders, plus language selection and handoff. Tests do not judge translation quality.

Run the local UI and server as described in the source guide. Choose the language from the top-right controls, open the affected screen and inspect long names or counts in context. Check narrow windows, keyboard focus, tooltips and accessible labels. With extra languages registered, verify that the dropdown stays usable near viewport edges and exposes its expanded/collapsed state to assistive technology. For new languages, also check a reload, App launch, switching back to English, and the optional visual mode. Keep meaningful phrases together instead of adding spaces or hard line breaks to force one desktop layout.

Website and film changes use the website preview. For Markdown changes, run node scripts/check-docs.mjs after staging new files, then review GitHub's rendered Markdown and translated links. Additional checks for code changes follow Contributing.

12 KiB Raw Permalink Blame History