AskaEth
54857bc0fd
公开 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 / 动态字体回退（雏形）。
56 lines
3.4 KiB
C
56 lines
3.4 KiB
C
/*
|
||
* meow_ui_str.h — SDK 字符串资源（i18n 雏形，§13.meow_str_*）。
|
||
*
|
||
* 定位：公开 SDK 前，系统/App UI 文案不得再硬编码在 C 源码里——第三方开发者必须能按
|
||
* 系统 locale 拿到对应语言文案，且能在不改 SDK 二进制的情况下用 TF 卡覆盖/追加。
|
||
* 本头声明字符串资源框架的**对外 API**（追加式，既有 App 零改动）。
|
||
*
|
||
* 单表双语内置（zh_cn = 内置默认 / en_us），四层取值优先级（见 meow_ui_str.c）：
|
||
* meow_str(id)：按当前 locale 取串；override 覆盖表 > 内嵌当前语言 > 内嵌内置默认(zh_cn)；
|
||
* 全程不可得则原样返回 id（调用方永不见 NULL）。
|
||
* meow_strf(out,outsz,id,...)：取串后按 snprintf 语义格式化进调用方缓冲（自带 NUL 终止）。
|
||
* meow_str_set_locale(locale)：切当前 locale（"zh_cn"|"en_us"），即时生效 + 重载 TF 覆盖表
|
||
* + best-effort 持久化到板载 settings.conf 的 ui.locale。
|
||
*
|
||
* 依赖：纯 libc（stdio/stdlib/string/stdarg），宿主 gcc 可直接编译单测；不依赖其它 SDK 对象。
|
||
* - locale 初值：启动首次调用惰性读系统设置 settings.conf 的 `ui.locale`，缺省 "zh_cn"。
|
||
* - TF 覆盖表：`<MEOW_DATA_DIR>/../strings/<locale>.txt`（即 MeowData/<pkg>/strings/，见
|
||
* §9.2 数据目录约定），`id=text` 行格式 UTF-8；无卡/无文件/不含该 id → 内嵌表兜底。
|
||
* - 热路径（meow_str）零 malloc：内嵌为编译期静态表，覆盖表为启动加载的静态数组。
|
||
*
|
||
* 边界（§13 明示不做，写清理由）：
|
||
* 不做复数规则 / BiDi / RTL / 动态字体回退——当前形态是「按 locale 取整串」的 i18n 雏形，
|
||
* 面向 480×720 单行/短文案 UI；复数变体需占位符格式化协议，BiDi/RTL 需文本整形 + 布局镜像，
|
||
* 两者都超出「字符串资源外置」的最小必要范围，留待后续批次。
|
||
*/
|
||
#ifndef MEOW_UI_STR_H
|
||
#define MEOW_UI_STR_H
|
||
|
||
#ifdef __cplusplus
|
||
extern "C" {
|
||
#endif
|
||
|
||
/* 按当前 locale 取 id 对应的文案。id 形如 `域.名`（common.ok / player.pause）。
|
||
* 返回静态字符串（内嵌表或覆盖表；永不返回 NULL）。未知 id 原样返回 id。 */
|
||
const char *meow_str(const char *id);
|
||
|
||
/* 取 id 文案后按 snprintf 语义格式化进 out（outsz 为缓冲字节数，含 NUL）。
|
||
* 返回 snprintf 样式的「应写入字符数」（不截断）；out==NULL 或 outsz<=0 返回 -1。
|
||
* 设计理由：调用方自带缓冲，避免静态/线程局部缓冲在 IME/模态等重入路径的竞态，
|
||
* 且与 SDK 既有 snprintf 习惯一致（无格式参数时等价深拷贝 meow_str 结果）。 */
|
||
int meow_strf(char *out, int outsz, const char *id, ...);
|
||
|
||
/* 设当前 locale（识别 "zh_cn"|"en_us"；任意串作为覆盖表文件名 + 内嵌按非 en 处理为内置默认）。
|
||
* 即时生效（下次 meow_str 即按新 locale）；重载该 locale 的 TF 覆盖表；
|
||
* best-effort 持久化到 settings.conf 的 ui.locale（失败静默，运行时仍切换）。
|
||
* 须在 App 主线程（UI 线程）调用，避免与 meow_str 并发写覆盖表。 */
|
||
void meow_str_set_locale(const char *locale);
|
||
|
||
/* 当前生效 locale（内部缓冲；未初始化时读 settings 后返回，默认 "zh_cn"）。 */
|
||
const char *meow_str_locale(void);
|
||
|
||
#ifdef __cplusplus
|
||
}
|
||
#endif
|
||
#endif /* MEOW_UI_STR_H */
|