国际化与时区

返回总览

语言和时区不会改变 workflow 的主线，却会直接影响交互文本、日志内容和保存时间

支持的内置语言

当前内置两套 locale

• en-US
• zh-CN

也可以通过 locales 追加或覆盖资源

默认语言如何解析

createWorkflowI18n 会按下面顺序推断语言

1. options.locale
2. options.resolveLocale()
3. 环境变量

环境变量的读取顺序如下

1. CLACK_KIT_LOCALE
2. APP_PROMPT_LOCALE
3. MISE_TASK_LOCALE
4. LC_ALL
5. LC_MESSAGES
6. LANG
7. 最终回落到 en-US

当前内置规则会把以 zh 开头的环境值归到 zh-CN，其余默认归到 en-US

如何追加 locale 资源

import { createWorkflowKit, createI18nLocales } from 'clack-kit';

const kit = createWorkflowKit({
  locale: 'zh-CN',
  locales: createI18nLocales({
    'zh-CN': {
      custom: {
        done: '处理完成',
      },
    },
  }),
});

追加资源时，内置和自定义资源会合并，不必整份重写

时区如何解析

默认时区解析顺序是

1. options.timeZone
2. options.resolveTimeZone()
3. timedatectl
4. /etc/timezone 或 /etc/localtime
5. Intl.DateTimeFormat().resolvedOptions().timeZone
6. TZ 环境变量
7. 最终回落到 UTC

这意味着在容器、服务器和本地环境里，时区大多能自动命中当前系统设置

语言与时区会影响哪些地方

• context.locale 和 context.timeZone
• 结构化文案翻译
• 日志文件里的时间显示
• 快照中的 locale 与 timeZone 字段

单次运行覆盖语言和时区

await kit.run(workflow, {
  locale: 'en-US',
  timeZone: 'Asia/Shanghai',
});

这种覆盖只影响当前这一次运行，不会反写到 kit 的默认配置中

下一步建议

• 想查 locale 和 timeZone 在运行结果中的位置，看 运行时上下文
• 想查 kit 配置总表，看 API 参考