用途:为 Factorial Code 工作区提供多语言支持。工作区中每种语言对应一个放在 i18n/<locale>.yaml 的翻译键值 YAML 文件,像其他资源一样由 CLI 同步。fcode.i18n("key") 按当前执行所用语言解析键,可用于进程代码、模块代码,以及表单 schema(服务端替换)。
主要能力:键可用点号寻址,嵌套写法与扁平点号键等价,便于子工作区按单个键覆盖父级。支持 %{name} 占位符插值。可用 options 指定 locale(值可为运行时动态表达式,便于一个执行内使用多种语言)或 version 版本标签。fcode.i18n.locale 返回执行语言。键无翻译时解析为键本身,不会抛错。
使用方式:CLI 命令有 fcode i18n:pull、fcode i18n:status、fcode i18n:add <locale>、fcode i18n:push、fcode i18n:remove <locale>、fcode i18n:reset,聚合的 fcode pull/push/status 也包含 locales。本地运行可用 fcode run my-process --locale pt-BR。REST 接口为 /{team}/rest/locales 系列,PUT 做 upsert;SDK 提供 FcodeI18n 的 list/set/delete;MCP 提供 get_locales、get_locale、save_locale、delete_locale。表单 schema 中以字符串形式写 fcode.i18n(...),参数须为扁平标量对象,渲染语言由嵌入的 locale 或 data-fcode-form-locale 决定。
适用场景:表单、Webhook、手动运行、定时任务、重跑等触发方式各自选定执行语言;未指定时用 settings.json 的 primaryLocale,未设置则按字母序第一个语言。
限制与注意:绝不可给 fcode.i18n 起别名,键必须是硬编码字符串字面量,否则翻译不会随执行下发。locale 标识符大小写敏感,格式为 ^[A-Za-z0-9][A-Za-z0-9_-]{0,19}$,不含点号。i18n/<locale>.inherited.yaml 只读且被 gitignore,不可编辑。locale 是表单与 Webhook 端点的保留名,会被剥离,业务数据请另取名。参数字符串中的 version 必须是内联字面量字符串。单个 locale 文件上限 256 KB。无自动提取命令,抽取硬编码字符串需手动完成。