Create ui-text.md

man/ui-text.md

@@ -0,0 +1,67 @@
+# 自定义 UI 文本
+
+从 Blessing Skin 5.0.0 开始，您可以在管理面板中的「多语言」页面自定义 Blessing Skin 上的 UI 文本（同时也包括后端返回的消息文本）。
+
+## 理解概念
+
+对于每一条文本，都有三个属性，分别是「分组」、「键」、「文本」。
+
+以用户仪表盘中关于积分系统介绍的那段文本为例，在 Blessing Skin 内部，是通过调用 `trans('user.score-intro.introduction')` 来获取该文本的。
+
+### 分组
+
+上面的整个 `user.score-intro.introduction` 可被小数点分成三段，其中第一段就是「分组」。以刚刚的文本为例，这里的分组就是 `user`。
+
+实际上，它是 Blessing Skin 目录下 `resources/lang/{xxx}/`（其中 `xxx` 为语种，如 `en` 或 `zh_CN`）下的文件名（不含扩展名，即 `.yml`）。
+例如，上面提到的那条文本就位于 `resources/lang/{xxx}/user.yml` 文件内。
+该目录下还有 `admin.yml`、`skinlib.yml` 等文件，所以相应地，它们的「分组」就是 `admin`、`skinlib`，依此类推。
+
+### 键
+
+还是以 `user.score-intro.introduction` 为例。键就是除了「分组」后剩下的部分。
+所以对于这条文本，它的键就是 `score-intro.introduction`。
+
+但要注意，在语言文件（YAML 文件）里，文件结构并不是像这个键那样为扁平化结构，而是树状结构，是嵌套的。
+打开 `resources/lang/{xxx}/user.yml` 文件，我们就可以发现，该条文本位于 `score-intro` 块中的 `introduction` 条。
+
+### 文本
+
+就是该条目的具体文本内容。在大多数情况下，文本内容只能是单行的。
+
+## 添加新条目
+
+在页面右方的表单可以添加新的条目，填写好「分组」、「键」、「文本」并提交后，如果该条文本在 Blessing Skin 有定义过，那么刷新页面即可生效。
+
+以修改「签到」按钮的文本为例。该条文本的分组是 `front-end`，键是 `user.sign`，文本则按您喜欢的去写，如「点此获取积分」。
+提交之后，刷新 `/user` 页面，就能看到按钮文本被更新。
+
+如果需要修改其它语种下的文本，请先切换站点语言。例如要修改英文下的某条文本，就需要先切换到英文页面，再去修改。
+单单修改某一语种下的文本，不会影响其它语种下的内容。
+
+## 修改现有条目
+
+在「多语言」页面的列表里，选择想要修改的条目，单击「修改」按钮，即可在弹出的提示窗口内对文本内容进行修改。
+
+如果需要修改其它语种下的文本，请先切换站点语言。
+
+注意，只能修改该条目的文本内容，不能修改分组或键。
+
+## 删除条目
+
+当您想将某条文本恢复为 Blessing Skin 的默认值，将该条目删除即可。
+
+::: warning
+注意：删除某条目时，会同时删除该条目在所有语种下的内容。
+:::
+
+## 被 JavaScript 渲染的文本
+
+由于 Blessing Skin 的不少页面都使用 Vue.js 进行渲染，因此它们无法直接获取 `admin.yml`、`user.yml`、`skinlib.yml` 等语言文件的内容。
+对于这部分的语言文本，它们均为于 `front-end.yml`。上面提到的「签到」按钮就属于这种情况。
+
+## 一点点技巧
+
+由于 Blessing Skin 中存在大量的文本，对于多数用户也难以清楚某条文本的分组和键是什么。
+
+这里有个技巧：想修改某条文本，然后全局搜索该条文本的内容，看看它是位于哪个分组下的什么键。
+有时会遇到相同文本内容，但分组或键不同的情况，这时候拿这些不同的分组和键，多试几次就可以。