/*
 * 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 */