Obsidian 文档采用了[Google 开发者文档风格指南](https://developers.google.com/style)。对于 Google 风格指南未包含的部分，请参照[Microsoft 风格指南](https://learn.microsoft.com/en-us/style-guide/)。 本页面列出了与 Google 风格指南有所偏差或值得强调的术语。 > [!tip] 帮助我们改进 > 很多文档在我们指定这些指南文件前就已经存在了。如果你发现任何违反指南的地方，请[创建一个问题](https://github.com/obsidianmd/obsidian-docs/issues/new)或向[Obsidian 开发者文档](https://github.com/obsidianmd/obsidian-docs)提交请求。 ## 概念的表述 注意，以下内容很多仅针对于英文语境进行规定。但仍推荐中文翻译者阅读原文以了解。 ### 术语 - 在“快捷键”与“热键”之间优先选择“快捷键”。 - 移动端使用“Obsidian 应用”，桌面端使用“Obsidian 应用程序”。 - 使用“同步”而非其他表述。 - 使用“搜索式”而非“搜索语句”。 - 在指代笔记中的一章节时，使用“小标题”而非“标题”。 - 使用“最大”而非“最大值”，使用“最小”而非“最小值”。 ### 产品名称 Obsidian 产品名称以“Obsidian”开头，例如“Obsidian 发布服务”和“Obsidian 同步服务”。 如果需要在一个段落中多次重复，则可以使用简称形式。 例如： _为了允许每个设备使用独有的设置，Obsidian 同步服务不会默认同步设置。因此你需要为每个设备决定是否开启同步设置。_ ### 用户界面和交互 - 使用**粗体**表示按钮文本。 - 在指代选择操作时优先使用“点击”而非“轻触”。 - 使用“侧边栏”而非“侧栏”。 - 指代用户执行命令时，使用“执行”。 当指代多个用户界面交互时，使用 →（U+2192）符号。例如，“**设置 → 社区插件**”。 ### 笔记、文件和文件夹 - 使用“笔记”指代仓库中的 Markdown 文件。 - 使用“文件”指代仓库中包含 Markdown 在内的所有文件。 - 使用“笔记名称”而非“笔记标题”。 - 使用“当前笔记”而非“活动笔记”。 - 使用“文件夹”而非“目录”。 - 使用“文件类型”而非“文件格式”，除非明确指的是文件内容的数据格式。 在不同笔记之间移动时，如果目标是隐藏的，则使用“打开”，如果源笔记和目标笔记在不同分栏中，则使用“切换”。 ### 设置中的参考 尽可能在 Obsidian 中使用描述性话语说明设置。除非： - 需要更深入了解如何以及何时使用它。 - 它经常被误用或被问及。 - 它会_显著_改变用户体验。 如果要提示用户注意特定设置，则考虑使用标注语法。 ### 表示方向的术语 英文语境下，将方向术语用作形容词时需要加连字符，用作名词时避免连字符。 在指代设置按钮时不要指示方向，因为设置按钮的位置取决于设备。 **推荐：** - 在**选择远程仓库**旁边，点击**选择**。 **不推荐：** - 在**选择远程存储库**右侧，点击**选择**。 ### 指令 对于指南名称、章节小标题和操作说明，请使用祈使句。因为祈使句简洁且以行动为导向，这对于用户更为直接。 ### 大小写 对于标题、按钮和小标题，使用*句式*而非*标题式*。在引用用户界面元素时，始终匹配界面文本的大小写。 ### 示例 优先选择实际示例而非无意义术语。 **推荐：** - `task:(来电 OR 日程)` **不推荐：** - `task:(foo OR bar)` ### 按键名称 在引用键盘上的字符名称时，在按键名称后使用括号补充具体字符： **推荐：** - 在单词前加一个连字符（-）。 **不推荐：** - 在单词前加别的符号。 ### Markdown 在 Markdown 块间使用换行： **推荐：** ```md # 标题 1 这是一个章节。 1. 第一项 2. 第二项 3. 第三项 ``` **不推荐：** ```md # 标题 1 这是一个章节。 1. 第一项 2. 第二项 3. 第三项 ``` ### 图像 用“**宽度** x **高度** 像素”来描述图像或屏幕尺寸。 **示例：** 推荐的图像尺寸：1920 x 1080 像素。 ## 图标和图像 当需要解释或展示无法用文字描述的 Obsidian 应用程序重要部分时，可以使用图标或图像。您可以将图像保存在文档的“附件”文件夹中。 - 图像应使其所对应的文本更易理解。 **示例**：启用后，[[字数统计]] 插件将在底部状态栏中创建一个新条目。 ![[Style-guide-zoomed-example.png#interface|300]] - 图像应为`.png`或`.svg`格式。 - 如果图像在笔记中看起来太大，请在 Obsidian 外部缩小它，或根据[[插入文件|在笔记中嵌入图像]]中解释的方式调整其尺寸。 - 在极少数情况下，您可能需要将特别大或复杂的图像放在[[标注|可折叠标注框]]中。 - 对于弹出窗口和模态窗口，则需要显示整个 Obsidian 应用程序的图像。 ![[Style-guide-modal-example.png#interface]] ### 图标 [Lucide](https://lucide.dev/icons/) 可以与 Obsidian 自定义图标一起使用，以用于展示更多功能。 **示例:** 在功能区中，选择 **新建白板** ( ![[lucide-layout-dashboard.svg#icon]] ) 可以在当前文件夹中创建并打开一个白板文件。 **图标使用指南** - 图标文件需要保存在 `附件/图标` 文件夹中。 - 对于 Lucide 图标，需要在文件名称前加 `lucide-` 前缀。 - 对于 Obsidian 图标，需要在文件名称前加 `obsidian-icon-` 前缀。 **示例:** 新建白板的图标应命名为 `lucide-layout-dashboard`. - 尽可能使用 SVG 格式的图标。 - 图标大小应为 18 x 18 像素，同时有 1.5 的轮廓宽度。这些你可以在 SVG 的元数据中进行调整。 > [!info]- 在 SVG 中调整图标大小和轮廓粗细 > ```html > <svg xmlns="http://www.w3.org/2000/svg" width="WIDTH" height="HEIGHT" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="STROKE-WIDTH" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-layout-dashboard"><rect width="7" height="9" x="3" y="3" rx="1"/><rect width="7" height="5" x="14" y="3" rx="1"/><rect width="7" height="9" x="14" y="12" rx="1"/><rect width="7" height="5" x="3" y="16" rx="1"/></svg> >``` - 在嵌入图像中，利用 `icon` 锚点调整图标周围的间距，使其与附近文本对齐整齐。 - 文字描述时，图标应该用括号括起来。 ( ![[lucide-cog.svg#icon]] ) **示例**：`( ![[lucide-cog.svg#icon]] )` ### 图像锚点 图像锚点可对嵌入图像的样式进行更改。 > [!warning] 实时预览下需注意 > 图标锚点在**实时预览**中不会正确显示。请使用**阅读视图**确认已应用锚点。 **图标锚点** `![[lucide-menu.svg#icon]]` 图标锚点可以使得图标垂直对齐，从而正确地指示界面元素。 第一个菜单图标使用了图标锚点（ ![[lucide-menu.svg#icon]] ），而第二个菜单图标（ ![[lucide-menu.svg]] ）没有。 **界面锚点** `![[Vault picker.png#interface]]` 界面锚点将在图像周围添加装饰性阴影。在第一张图像中，应用了锚点。 ![[Vault picker.png#interface]] 相比之下，第二张图像没有应用锚点。 ![[Vault picker.png]] **轮廓锚点** `![[Backlinks.png#outline]]` 轮廓锚点在图像周围添加细微的边框。在第一张图像中，应用了轮廓锚点。 > [!tip] 观察图像的左下角以查看区别。 ![[Backlinks.png#outline]] 第二张图像未使用轮廓锚点。 ![[Backlinks.png]] ### 优化 图像会拖慢页面加载时间，并占用[[发布服务简介|Obsidian 发布服务]]存储空间。优化图像可减小文件大小，同时保持图像视觉的完整性。 图像和图标都应进行优化。 > [!success] 图像优化工具 > 以下是减小图像大小的推荐程序。 > - **Windows:** [FileOptimizer](https://sourceforge.net/projects/nikkhokkho/) > - **macOS:** [ImageOptim](https://imageoptim.com/) > - **Linux/Unix** [Trimage](https://trimage.org) > > 我们建议将优化率设置在 65-75%。 ## 翻译 翻译时尽可能帮助上下文也是通俗易懂的。因此翻译需要包含以下要素： - 笔记名称 - 文件夹名称 - 别名 - 附件名 - 链接的锚文本