国际化

kavina 提供轻量的 i18n 工具，用于部件的多语言支持。

定义语言包

使用 defineI18n 定义翻译字典：

import { defineI18n } from "kavina/tools";

export default defineI18n(() => [
  { zh: 0, en: 1 },
  {
    title: ["标题", "Title"],
    content: ["内容", "Content"],
    save: ["保存", "Save"],
  },
]);

defineI18n 接收一个返回数组的函数，数组包含两部分：

第一部分：语言索引映射，如 { zh: 0, en: 1 }
第二部分：翻译字典，每个 key 对应一个按语言索引排列的字符串数组

返回的函数按需调用，翻译字典只会初始化一次（惰性求值）。

在 schema 中使用

部件的 schema 函数接收 lang 参数，结合 i18n 为不同语言生成默认配置：

import i18n from "./i18n.ts";

export default defineWidget(() => ({
  name: "button",
  schema({ lang }) {
    return {
      widget: this.name,
      text: i18n("text", lang),
      label: i18n("label", lang),
    };
  },
}));

在组件中使用

通过 context 获取当前语言，动态切换显示文本：

vue

<script setup>
import { useContext } from "kavina/hooks";

const { lang } = useContext();
</script>

<template>
  <span>{{ lang === "zh" ? "保存" : "Save" }}</span>
</template>

exchange

exchange 用于处理 string | ((lang: string) => string) 类型的字段，如 PluginItem 的 title：

import { exchange } from "kavina/tools";

const text = exchange(plugin.title, lang.value);

传入字符串时直接返回，传入函数时以当前语言调用并返回结果。

默认语言

未传递 lang 参数时，defineI18n 返回字典数组的第一项（索引 0）。语言索引映射中，zh: 0 表示中文为默认语言。只需调整索引映射即可切换默认语言。

提前绑定

defineI18n 返回的函数支持通过 bind 提前固定翻译 key，生成一个只需要语言参数的函数：

const i18n = defineI18n(() => [/* ... */]);

// 提前绑定 key
const t = i18n.bind(null, "save");

// 后续调用只传语言即可
t("zh"); // '保存'
t("en"); // 'Save'

这在需要将翻译函数传递给其他组件时特别有用——接收方只负责传语言，不需要关心翻译 key。例如 PluginItem 的 title 字段：

plugins: [
  {
    title: i18n.bind(null, "widgets"), // 调用者只需 title(lang)
    icon: IconCircleDashedPlus,
    component: WidgetsPanel,
  },
];

国际化 ​

定义语言包 ​

在 schema 中使用 ​

在组件中使用 ​

exchange ​

默认语言 ​