sdk(ui): 字符串资源外置（i18n 雏形 §13）—— meow_str_* + 内嵌双语表 + TF 覆盖表 + 控件接入
公开 SDK 前把 SDK/App 硬编码文案外置：新增 meow_str/meow_strf/meow_str_set_locale/ meow_str_locale，按当前 locale 取串（永不 NULL），第三方开发者可做多语言。 - 新增 include/meow_ui_str.h + meow_ui_str.c：取串优先级 = TF 覆盖表 > 内嵌当前语言 (en_us→en 其余→zh) > 内嵌内置默认(zh_cn) > 原样返回 id。内嵌双语表（common.* 21 条 + ime.* 9 条）；热路径零 malloc（编译期静态表 + ≤256 静态覆盖数组）；纯 libc 宿主可单测。 - locale 存系统设置 settings.conf 的 ui.locale（默认 zh_cn，首次调用惰性读取）； meow_str_set_locale 即时切换 + 重载覆盖表 + best-effort 持久化（流式改写保留其它行）。 - TF 覆盖表 MeowData/<pkg>/strings/<locale>.txt（id=text 行，UTF-8，'=' 两侧去空白）； 无卡/无文件/无该 id → 回落内嵌。meow_strf 用调用方缓冲（snprintf 语义，重入安全）。 - SDK 控件接入：dialog 默认按钮 OK/CANCEL + INPUT 占位、IME 键面/徽标（空格/确定/拼英/ ?123/清/拼音/（无候选）/中）改走 meow_str；空态/加载态给 App 提供 common.no_data/loading。 - 测试：新增 test_meow_ui_str.c（内嵌回退/TF 覆盖优先级/未知 id 回退/切 locale 即时生效/ 查找正确性/meow_strf，tmp+env 两模式）；全量宿主回归（widgets/dispatch/box/anim/scroll/ listvirt/theme/ime_fix/pinyin/overlay/notif/sdk_input_keys/p1p2p3/config/vol/sb_collapse/ notify_*) 0 回归；交叉 zig-mipsel -Wall -Wextra 0 warning。 - 文档：MEOW_APP_SDK.md 新增 §13（字符串资源/i18n，遗留顺延为 §14）；docs/APP_DEV_GUIDE.md 新增 §7.11。各宿主 test_*.c 头注释补 meow_ui_str.c 编译依赖。 边界（§13.7）：仅 zh_cn/en_us 整串取用；不做复数规则 / BiDi / RTL / 动态字体回退（雏形）。
This commit is contained in:
AskaEth committed
1 parent
d7bf62f448
commit
54857bc0fd
23 files changed
+615
-29
No files matched your search
+57
-1
@@ -29,6 +29,7 @@
|
||||
| `meow_ui_config.h` | 应用配置读写 | §9.2 |
|
||||
| `meow_ui_font.h` | 字体 | §5.7 卡片字体列表 + §10 字体分层 |
|
||||
| `meow_ui_audio.h` | 独占音频客户端 | §11 |
|
||||
| `meow_ui_str.h` | 字符串资源/i18n | §13 `meow_str`/`meow_strf`/`meow_str_set_locale` |
|
||||
|
||||
其余按需显式 include、**不**随伞头发布的模块头（原样保留、本次未改）：`meow_ui_view.h` / `meow_ui_nav.h` / `meow_ui_media.h` / `meow_ui_sys.h` / `meow_ui_vol.h`。`meow_ui_internal.h` 为 SDK 内部件，不随伞头发布。
|
||||
|
||||
@@ -1334,7 +1335,62 @@ void meow_scroll_set_friction(meow_scroll *s, int tau_ms); /* 默认 180ms
|
||||
|
||||
---
|
||||
|
||||
## 13. 遗留 / 待实现
|
||||
## 13. 字符串资源 / i18n（`meow_str_*`，2026-09-02 追加）
|
||||
|
||||
> **性质**：字符串资源外置（i18n 雏形）——公开 SDK 前，SDK/App 的 UI 文案不再硬编码在 C 源码：第三方开发者按系统 locale 取对应语言串，且可不改 SDK 二进制用 TF 卡覆盖/追加。**追加式**：新头 `include/meow_ui_str.h` + 新 `.o` `meow_ui_str.c`；既有 `meow_ui.h` 伞头自动聚合（仅新增 #include），既有 API/控件签名一行未改。
|
||||
|
||||
### 13.1 API（追加式，纯 libc，宿主 gcc 可直接单测）
|
||||
|
||||
```c
|
||||
const char *meow_str(const char *id); /* 按当前 locale 取 id 文案；静态串，永不 NULL；未知 id 原样返回 id */
|
||||
int meow_strf(char *out, int outsz, const char *id, ...); /* 取串后按 snprintf 语义格式化进 out（自带 NUL）；out==NULL/outsz<=0→-1 */
|
||||
void meow_str_set_locale(const char *locale); /* 切 locale（"zh_cn"|"en_us"），即时生效 + 重载 TF 覆盖表 + best-effort 持久化 ui.locale */
|
||||
const char *meow_str_locale(void); /* 当前生效 locale（缺省 "zh_cn"） */
|
||||
```
|
||||
|
||||
> `meow_strf` 用**调用方自带缓冲**（而非静态/线程局部），避免 IME/模态等**重入路径**的缓冲竞态，且与 SDK 既有 `snprintf` 习惯一致（无格式参数时等价深拷贝 `meow_str`）。这是把任务书 `meow_strf(id, ...)` 落地为 `(out, outsz, id, ...)` 的定案（可重入、线程安全优先于少一个参数）。
|
||||
|
||||
### 13.2 取值优先级（四层，逐层回落，永不返回 NULL）
|
||||
|
||||
1. 当前 locale 的 **TF 覆盖表**：`MeowData/<pkg>/strings/<locale>.txt`，`id=text` 行格式 UTF-8，`meow_str_set_locale` 加载进静态数组（≤256 条）；
|
||||
2. 内嵌表**当前语言**（`en_us→en`，其余→`zh`）；
|
||||
3. 内嵌表**内置默认**（`zh_cn`，locale 缺省/未知语言回落）；
|
||||
4. 仍不可得 → **原样返回 `id`**（调用方可展示 id/打点，绝不见 NULL）。
|
||||
|
||||
> 无卡/无覆盖文件/无该 id → 自动回落**内嵌双语默认表**（编译进二进制，必可用）。内嵌表含 `common.*`（确定/取消/返回/确认/完成/保存/删除/编辑/搜索/输入/请输入/请选择/加载中/暂无数据/重试/失败/重试失败/关闭/未知/设置/点击确定编辑，共 21 条）+ `ime.*`（空格/确定/取消/拼英/?123/清/拼音/（无候选）/中，共 9 条），`zh_cn`+`en_us` 双语。
|
||||
|
||||
### 13.3 ID 规范
|
||||
|
||||
`域.名`（`common.ok` / `common.cancel` / `player.pause`）。SDK 自带 `common.*` 通用组 + `ime.*` IME 键面组；第三方可自建 `域`（如 `player.*`），经 TF 覆盖表追加，不改 SDK 二进制。
|
||||
|
||||
### 13.4 locale 存系统设置
|
||||
|
||||
locale 权威值 = 板载 `settings.conf` 的 `ui.locale`（默认 `zh_cn`）。SDK 首次调用**惰性读取**；`meow_str_set_locale` 即时切换（运行时）并 **best-effort 持久化**回 `ui.locale`（流式改写、保留其它行——绝不 O_TRUNC 整文件；失败静默，切换仍生效）。SDK 与 launcher 系统组件读同一份，后续系统 UI 复用同键即当前语言。
|
||||
|
||||
### 13.5 性能
|
||||
|
||||
**启动时一次加载**到静态线性表：内嵌为编译期静态表；覆盖表为启动/切 locale 时的静态数组（≤256 条）。`meow_str` 只做 O(n) 线性扫描（表小可接受），**热路径零 malloc**（无堆申请、无引用计数）。
|
||||
|
||||
### 13.6 SDK 控件接入
|
||||
|
||||
- **dialog**（§5.8.6）：默认按钮 `"CANCEL"/"OK"` → `meow_str("common.cancel"/"common.ok")`；INPUT 预览占位 `"(tap OK to edit...)"` → `meow_str("common.tap_ok_edit")`。
|
||||
- **IME**（§5.1）：拼音键面/徽标（空格/确定/拼英/?123/清/拼音/（无候选））与 ASCII/NUM 顶条「中」→ `meow_str("ime.*")`。
|
||||
- **空态/加载态**：SDK 不硬编码空态文案；`common.loading`/`common.no_data` 供 App 空态/加载中直接用（如 `meow_listview_set_empty_text(w, meow_str("common.no_data"))`）。
|
||||
- **launcher 等系统组件**：后续经同框架接入（本任务只管 SDK 侧；launcher 复用同 `settings.conf ui.locale`）。
|
||||
|
||||
### 13.7 边界（明示不做，写清理由）
|
||||
|
||||
- **不做复数规则**：需占位符格式化协议 + 每语言复数表，超出「按 locale 取整串」的最小必要范围；
|
||||
- **不做 BiDi / RTL / 动态字体回退**：需文本整形 + 布局镜像 + 字体回退策略，面向 480×720 单行/短文案场景暂不需要；
|
||||
- 当前形态为 i18n **雏形**，复杂变体（复数/语言方向/字体重载）留后续批次；locale 仅 `zh_cn`/`en_us` 双语（任意串作覆盖表文件名，内嵌按非 `en` 视为内置默认）。
|
||||
|
||||
### 13.8 同步重编注意
|
||||
|
||||
`build_sdk.sh` OBJS 新增 `meow_ui_str`；`meow_ui_str.o`（含内嵌表）+ `meow_ui_dialog.o`/`meow_ui_ime.o` 重编 → **链 `meow_ui.a` 的 App 需重链**（一键 `build_sdk.sh`）。既有 App **不改源码**即零回归（仅按钮/键面文案随 locale 变化）。宿主回归测试需在编译命令补 `meow_ui_str.c`（各 test_*.c 头注释已同步）。
|
||||
|
||||
---
|
||||
|
||||
## 14. 遗留 / 待实现
|
||||
|
||||
1. `meow_ui` 渲染后端需从 launcher 里**抽公共绘制实现**（`back_buf`/`meow_dirty_*`/`meow_present`/`meow_font_bind` 目前是 launcher 静态函数——需提取为可链接的 `meow_ui_gfx` 或改为共享 obj，注意 launcher 与 app 是**不同进程**，不能共享同一 back_buf；`meow_ui.a` 是**独立库**，内部自建 fb 上下文，不复用 launcher 的全局 `g_dirty`）。
|
||||
2. 输入线程优先级：vs 主循环 10ms 热键轮询的竞态，需在 B1 实现时定义清楚（应用进程内独立事件循环，不与 launcher 抢）。
|
||||
|
||||
Reference in new issue
Block a user