[Feature Request]: 自定义属性添加本地化，但是labelPrefix

[otomad]

Problem Statement | 需求背景

我在使用枚举时，除了枚举值本身的文本标签之外，还一般需要一个描述标签来描述这个值是做什么用的。这就需要两个字段需要翻译。

刚才看到了 #82 正好添加自定义字段本地化的功能，正好可以一起说一下。

Package Scope

enum-plus (core)

Feature Description | 功能描述

假设 #82 方案实施的话，那么我的情况大概就像这样：

const WeekEnum = Enum({
    Sunday: { value: 0, label: "week.sunday", description: "descriptions.week.sunday" },
    Monday: { value: 1, label: "week.monday", description: "descriptions.week.monday" },
    Tuesday: { value: 2, label: "week.tuesday", description: "descriptions.week.tuesday" },
}, { autoLocalizeMeta: ["description"] });

但是我还想用 labelPrefix，此时理论上可以简化为：

const WeekEnum = Enum({
    Sunday: 0,
    Monday: 1,
    Tuesday: 2,
}, {
    autoLocalizeMeta: ["description"],
    labelPrefix: "week",
    descriptionPrefix: "descriptions.week",
});

但是直接逐个写 labelPrefix 和 descriptionPrefix 肯定是不现实的，肯定需要某种变通方案，但是我还没有方案思路。

Use Cases | 使用场景

只要需翻译字段的键名是保持规律的，就可以有效减少本地化的代码量。

Importance | 重要性评估

No response

Feature Level | 特性级别

Core Library (核心库)

Proposed Solution (Optional) | 建议方案(可选)

其它信息

不过我还有个其它需求，就是将 #82 中提到的 autoLocalizeMeta 属性添加到 enum plus 全局属性中，因为只要字段名是指向性的，其必定在所有枚举中都是可翻译的。像这里的 description 字段只要每个枚举中出现了就一定是可翻译的。因此我可以直接将其加入全局属性中，没必要每个枚举都写一遍 autoLocalizeMeta 属性。

此外，由于我的所有描述翻译键名都是严格在 labelPrefix 前面加上“descriptions.”，因此理论上还可以再进一步简化，例如在全局配置上添加某种配置后（比如类似于 autoLabel 再来个 autoDescription 之类的），那么在每个枚举中也都可以不用配置 descriptionPrefix 直接使用了。不过这个想法太过于抽象了，如果你没有太好的思路的可以先不实现。

[shijistar]

你的提议有一定合理性，把autoLocalizeMeta提升为全局设置，对于包含大量相同扩展字段的项目是有益的，可以简化枚举定义的代码。

如果要全局范围为扩展字段设置prefix，可以考虑为autoLocalizeMeta增加一种map配置格式。例如，

Enum.config.autoLocalizeMeta = {
  description: {
    labelPrefix: 'description.week.'
  }
};

这样就省去给每个枚举单独设置 labelPrefix 了

[otomad]

关于非全局我的一个想法是将 labelPrefix 配置成对象格式，例如：

const WeekEnum = Enum({
    Sunday: 0,
    Monday: 1,
    Tuesday: 2,
}, {
    autoLocalizeMeta: ["description"],
    labelPrefix: {
        label: "week.",
        description: "descriptions.week.",
    },
});

假如全局配置了 autoLocalizeMeta，也许它会简化为（？不确定）：

Enum.config.autoLocalizeMeta = {
    description: {
        labelPrefix: "descriptions.",
    },
};

const WeekEnum = Enum({
    Sunday: 0,
    Monday: 1,
    Tuesday: 2,
}, {
    labelPrefix: "week.",
});

[shijistar]

关于非全局我的一个想法是将 labelPrefix 配置成对象格式，例如：

我觉得没有必要把扩展字段的设置分散到两个配置里，meta相关的都内聚到autoLocalizeMeta中可能比较好一些。

假如全局配置了 autoLocalizeMeta，也许它会简化为（？不确定）：

这个有点意思，相当于让枚举“无中生有”添加了descriptions字段，这个会影响所有枚举，似乎有点太激进了😂，还是需要显式声明比较好一些。

[shijistar]

我有一个问题，在你的项目中你有使用过全局labelPrefix吗？

似乎使用全局了labelPrefix，就可以省略所有枚举的label字段了，但我感觉这里面似乎还有一个问题。

一般我们在国际化资源里都会使用命名空间来分类，例如，enums.week.Sunday、enums.color.Red、enums.currency.Dollar，每个枚举都有一个二级命名空间。

这样，在全局设置label前缀时就会有一个问题，我们只能设置到enums这一级，而不能设置到第二级，因为每个枚举都有不同的命名空间。

但如果真的设置为第一级的话，那国际化资源中就只能去掉第二级，让所有枚举都写到一起，这样既容易重名，也不优雅，也不好管理。

再顺着你的极致简化的思路，我觉得可以引入一个{name}占位符，同时给每个枚举设置各自的name，来解决所有问题。

Enum.config.labelPrefix = 'enums.{name}.';

const WeekEnum = Enum({
    Sunday: 0,
    Monday: 1,
    Tuesday: 2,
}, {
    name: "week",
});

这样应该就真的是极致简化的配置了！

i18n.json

{
  "enums.week": "Week",
  "enums.week.Sunday": "Sunday",
  "enums.week.Monday": "Monday",
}

app.tsx

WeekEnum.name; // Week
WeekEnum.named.Sunday.label; // Sunday

除了枚举项的名称，我们还可以为每个枚举命名，作为字段标题、列名时也很常用，一举多得。

[shijistar]

关于全局autoLocalizeMeta也可以极致简化。今天有点晚了，明天再细说。

[otomad]

让枚举“无中生有”添加了descriptions字段

确实有点太激进了，还是算了。但是全局 autoLocalizeMeta 属性还是有益的。

我有一个问题，在你的项目中你有使用过全局labelPrefix吗？

我从未使用过全局 labelPrefix，感觉应该也没啥用。因为几乎每个枚举的作用都不同，基本上不会存在相似的前缀之处。

一般我们在国际化资源里都会使用命名空间来分类

这可能是你觉得全局 labelPrefix 唯一的用处。但因为我用的是 i18next，它自带命名空间功能且可以指定默认命名空间，因此绝大多数情况我一般也不会用到命名空间，少数要改命名空间的情况，单独在这个枚举这里声明就好了。

假如用的不是 i18next 且真的需要全局 labelPrefix，为什么不去改 autoLabel 呢？因为 autoLabel 支持函数类型想咋改就咋改。

[otomad]

哦对我一般在翻译字符串字典文件中使用嵌套来表示所谓的二级命名空间，这样比扁平的键名更具有可读性。

既然如此，那么你刚才给出的扁平化字典其实是非法的（至少我用的在线翻译平台 Crowdin 就是如此，不管上传到 Crowdin 的源文件是嵌套的还是扁平的字典文件）：

{
  "enums.week": "Week",
  "enums.week.Sunday": "Sunday",
  "enums.week.Monday": "Monday",
}

假如切换成嵌套字典格式的话：

{
  "enums": {
    "week": {
      "Sunday": "Sunday",
      "Monday": "Monday"
    }
  }
}

"enums.week": "Week" 这一键值对就无法表示了。

我个人项目的话是改用 "enums.week._" 或 "enums.week.title" 来变通表示。（不过自己魔改了 i18next 封装了一个新的 t 函数使其支持自动加上 "._"）

[shijistar]

有一个解决办法，可以让autoLabel全局配置扩展一种map方式，把label、和扩展字段放到一起配置，和你前面建议的思路类似。

Enum.config.autoLabel = {
  namePrefix: "enums.",
  itemPrefix: {
    label: "enums.{name}.title",
    description: "enums.{name}.{item}.description",
  },
}

这样配置更灵活，无论i18next的配置形式使用flat风格，还是nested风格，都可以支持。

在扩展字段支持了国际化以后，label和meta本质上都是枚举项的字段之一，我也一直想把两者统一起来，，只是一直没有很优雅的方案。这个方案我觉得还不错，既能把name、label、meta字段都统一起来，而且精简了api，原来的labelPrefix和autoLocalizeMeta就可以去掉了。现在引入的国际化配置项好几个，容易让人迷惑。

你觉得怎么样？

只不过还有两个问题，

1. autoLabel这个名称最初是为label设计的，现在已经扩展到了name和meta字段，这个命名似乎有点狭窄了，但一时又没想到更贴切的命名，既简洁，又清晰。或者叫autoLocaleKey?
2. description、abbr、tooltip之类的扩展字段，都是和国际化相关，其实按照上面的全局设置就够了，没有必要出现在枚举声明里了。那这就有点尴尬，如果不声明的话，就有“无中生有”的嫌疑，而且也缺少TS类型的智能提示；如果声明的话，又不需要字段值，用空字符串的话也觉得怪怪的。

const WeekEnum = Enum({
    Sunday: { value: 0, description: "" },
    Monday: { value: 1, description: "" },
}, {
    name: "week",
});

[otomad]

label: "enums.{name}.title",
description: "enums.{name}.{item}.description",

请问这里的 name 和 item 实际情况是如何呢？可以举个范例吗？

---

然后现在全局的 autoLabel 配置做好了，那么各枚举独立的配置又该如何呢？

我现在已有不少情况，枚举的label是相同的prefix约定，但description却不同。这是因为label名称比较通用，可以直接在不同语境下复用，而description却不同，有针对不同语境下单独的区分以详细说明。这时使用全局的配置反而不太方便了。

[shijistar]

请问这里的 name 和 item 实际情况是如何呢？可以举个范例吗？

我写代码解释下哈，我们先说name和label，扩展字段可能有点复杂，后面再讨论。

main.ts

Enum.config.autoLabel = {
  namePrefix: "enums.", // Locale key prefix for enum name
  itemPrefix: {
    label: "enums.{name}.title", // Locale key template for enum item label
  },
}

i18n.json (nested风格)

{
  "enums": {
    "week": {
      "title": "Week",
      "Sunday": {
        "title": "Sunday"
      },
      "Monday": {
        "title": "Monday"
      }
    }
  }
}

app.tsx

const WeekEnum = Enum({
    Sunday: 0,
    Monday: 1,
    Tuesday: 2,
}, {
    name: "week",
});

WeekEnum.name; // Week
WeekEnum.items[0].label; // Sunday

这个示例主要是想展示，通过全局配置，我们可以给所有枚举放在同一个命名空间下，然后全局设置前缀，简化普通枚举的定义，省去label的配置，有点类似约定式编程。

你后面的问题，我正好有一个想法，可以稍后再讨论，先把上面的部分达成一个共识

[otomad]

首先有个问题，既然namePrefix、itemPrefix里面有花括号来填充因此也不一定是前缀了，autoLabel也支持其它meta字段因此也不只是label了，不如分别改成：nameTemplate、itemTemplate、autoLocalize？

那我也写一下假如我使用全局配置的话我的情况吧，看看对吗。因为我不喜欢把每个字段都单独写 title 和 description，不然要写很多重复的 title 和 description 键名太冗长了。

{
    enums: {
        datetime: {
             week: {
                 title: "Week",
                 sunday: "Sunday",
                 monday: "Monday",
                 tuesday: "Tuesday",
             },
        },
        descriptions: {
             datetime: {
                 week: {
                     title: "Set the current weekday.",
                     sunday: "The last day in a week, stands for the sun.",
                     monday: "The first day in a week, stands for the moon.",
                     tuesday: "The second day in a week, stands for the Mars.",
                 },
             },
        },
    },
}

Enum.config.autoLocalize = {
    nameTemplate: "enums:{name}.title",
    itemTemplate: {
        label: "enums:{name}.{item}",
        description: "enums:descriptions.{name}.{item}",
    },
};

枚举声明和你的一模一样就不写了。

然而 autoLocalize（原 autoLabel）其实还支持函数类型，因此也许可以把 name 和 item 插值改成函数参数也许会比现在的花括号表示更方便？尤其是像在这里其实还有键名大小写的转换操作，但在我这里没表示出来。

而且我也有不少情况枚举的标题和 label 前缀不一致，假如这样写的话，等于说原 labelPrefix 值的作用被 title 给取代了，也会产生不正确。

其实我这个 issue 本意还是讨论单个枚举的 itemTemplate（原 labelPrefix）情况，然后附加地想让原 autoLocalizeMeta 实现全局配置，因为在我这里出现 description 字段就一定是需要翻译的。而要实现全局的 autoLocalize（原 autoLabel 或 labelPrefix）其实已经超出我所设想的范围了（而且估计我也用不到）。后面的单个枚举的配置方法就先听听看你的想法讨论一下吧。

[shijistar]

我觉得你建议的命名更好一些。是的，autoLocalize仍然继续支持函数形式，你还可以继续使用函数形式，执行自己特有的转换逻辑。

至于单个枚举的配置，可以同样复用这一套配置范式，只不过是定义在单个枚举级别的。全局配置用来兜底，处理大多数符合规范的枚举，单个级别的用来差异化处理特殊的。

因此也许可以把 name 和 item 插值改成函数参数也许会比现在的花括号表示更方便？

好的，现在autoLabel函数已经把 item 对象作为参数传递进来了，可以使用item.key来代替{item}插值，未来可以再增加一个options属性把构造时的options传递进来，就可以使用options.name来代替{name}插值。如果你在autoLocalize方法中还需要其他自定义数据的话，都可以通过options传递进来。

其实已经超出我所设想的范围了（而且估计我也用不到）

我觉得你可以使用 autoLocalize.nameTemplate/itemTemplate 可以作为兜底方案吧，来解决那些有规则的枚举，然后使用函数形式来处理那些没有规则的，或者直接为每个item手写完整的key。所以我理解，两种可以混合使用，我理解这一套新的配置范式对你还是有些帮助的吧。

如果autoLocalize（对象+函数）这一套配置范式能满足你的话，我计划把labelPrefix和autoLocalizeMeta废弃掉了。所以我需要你的反馈，以确保这样的改动是兼容的，旧的代码必须有可用的迁移路径。

其实已经超出我所设想的范围了

哈哈，其实是你的话题启发了我，我希望借这个机会能把配置系统重构一下，API更简洁清晰，感谢你的反馈和贡献。我觉得你们项目的使用方式比较复杂，如果能够解决你的痛点，满足你的使用需求的话，我相信大多数项目也可以使用起来，至少我们项目简单的多，所有枚举相关的国际化都内聚到一块，是有规律前缀的。

[shijistar]

description、abbr、tooltip之类的扩展字段，都是和国际化相关，其实按照上面的全局设置就够了，没有必要出现在枚举声明里了。那这就有点尴尬，如果不声明的话，就有“无中生有”的嫌疑，而且也缺少TS类型的智能提示；如果声明的话，又不需要字段值，用空字符串的话也觉得怪怪的。

我还没介绍的就是关于扩展字段的配置形式，主要是针对下面这种情况的，

const WeekEnum = Enum({
    Sunday: { value: 0, description: "" },
    Monday: { value: 1, description: "" },
}, {
    name: "week",
});

也就是说，description已经通过全局配置能够resolve了，在单个枚举中仅仅起到一个声明字段存在的作用，上面这种方式有点奇怪，有点莫名其妙。我在想是不是下面这种配置方式比较好？

const WeekEnum = Enum({
    Sunday: 0,
    Monday: 1,
}, {
    name: "week",
    autoLocalizedMeta: ["description", "abbr"]
});

这样即可以在js运行时，自动把description、abbr扩展字段添加上，也能让TypeScript类型系统解析到，并能IDE的智能提示中列出来这两个字段（理论上应该可行，但我还没测试）。而且代码也比较清爽。

[otomad]

因为我感觉假如我每次都需要在每一个枚举里面写 autoLocalizedMeta: ["description"] 有些冗余。不过既然原来其实也有无中生有的 “label” 字段（假如我从未有意声明 label 字段，那么 label 字段的值与 key 是一致的），要不也可以允许全局配置后（但似乎须要手动配置 .d.ts 声明），直接隐式提供该字段？因为反正这些字段必须调用时才会获取值，也不会额外占内存或性能。做成 Proxy 就可以像当成函数一样调用就好了。

我计划把labelPrefix和autoLocalizeMeta废弃掉了。所以我需要你的反馈，以确保这样的改动是兼容的，旧的代码必须有可用的迁移路径。

我觉得没事，因为我本身也是比较喜欢激进派地使用最新版，假如有现有不兼容的情况我会立即修改我自己这边的代码以匹配库的最新 API。
唯一的缺点就是版本号这里一般规定必须要大版本号+1时才能完全删去旧API，有点麻烦。不过也许可以不用管？