user-interface.localization

OneDocs 的界面本地化能力负责为导航栏、功能页面、设置项及帮助内容提供中文与英文界面切换，并将语言选择作为用户界面体验的一部分与主题、模型及分析配置共同呈现。

Purpose and Scope

本文档说明 OneDocs 用户界面中与本地化直接相关的范围：语言切换入口、受语言影响的导航与页面文案、设置页面中的语言配置，以及本地化与其他界面功能之间的关系。内容依据现有界面说明整理；当前可见材料没有提供具体源码文件、翻译资源文件、键名、运行时 API 或持久化实现，因此这些实现细节不作推断。

本文不展开分析引擎、模型调用、RAG、存档数据格式或主题系统的内部实现。它们只在说明语言切换所在的界面位置时被交叉提及。有关分析流程请参阅分析相关页面；有关主题、字体、背景等视觉定制请参阅外观设置相关页面。

Overview

OneDocs 的界面由顶部导航栏和多个功能页面组成。导航栏右侧提供语言切换入口，当前界面说明明确列出的语言为中文和 English。设置页面的“通用”标签也提供语言设置，因此语言选择既可以从全局导航区域访问，也可以从设置区域理解和调整。

本地化覆盖的可见界面内容包括：

顶部导航标签：分析、存档、发现、关于、设置；
分析页中的功能模式、上传区、结果展示区及操作按钮；
设置页的通用、外观、模型三个标签及其配置项；
存档页、发现页和关于页的标题、说明与教程内容；
导航栏右侧的语言切换控件本身。

现有材料没有说明语言选择是否即时生效、是否写入本地存储、是否需要重新加载页面、是否影响分析结果内容，也没有说明缺少翻译键时的回退语言。因此使用或扩展本地化时，应以实际实现和翻译资源为准，不应将上述行为视为已确认的契约。

Architecture

从已知界面结构看，本地化能力位于全局导航与各页面文案之间：导航栏提供语言入口，各页面消费当前语言对应的界面文本。语言设置同时出现在“通用”设置中，说明它属于通用界面偏好，而不是某个单独业务页面的局部选项。

当前源材料不足以确认具体的本地化模块、资源文件、Provider、Hook、状态管理器或持久化适配器，因此无法可靠绘制包含代码组件名称的架构图。实现层架构：Implementation details not found in source。

已确认的界面关系

界面区域	与本地化的关系	已确认内容
顶部导航栏	提供全局语言切换入口	支持中文/English
通用设置	提供语言设置项	可切换中文/英文界面
分析页	展示受语言影响的操作和状态文案	文件上传、模式选择、结果查看等文案属于界面范围
存档页	展示历史记录相关界面文案	包含记录列表与结果查看区域
发现页	展示版本更新相关界面文案	包含版本列表和更新说明
关于页	展示项目说明和帮助内容	包含版本、简介、功能、帮助四个标签
设置页	展示配置分组与选项名称	包含通用、外观、模型三个标签

Language Entry Points

顶部导航栏语言切换

顶部导航栏右侧包含语言切换控件，与主题切换并列。界面说明将可选语言列为中文和 English。该位置适合作为跨页面的全局入口，因为无论用户当前位于分析、存档、发现、关于还是设置页面，都能从统一位置访问语言选择。

材料没有说明控件的具体形式，例如下拉菜单、按钮组或弹窗，也没有说明切换后是否保持当前路由。因此这些行为不应在集成代码或自动化测试中被假定。

通用设置中的语言设置

设置页面的“通用”标签包含“语言设置”，其用途是切换中文/英文界面。该设置与分析设置、数据管理、RAG 嵌入模型配置及开发者模式并列，表明它属于应用级通用偏好，而不是模型配置或分析模式配置。

语言设置和顶部导航语言切换描述的是同一个用户需求的两个入口。现有资料没有确认两者是否共享同一状态，也没有确认其中一个入口改变后另一个入口是否同步显示当前值；这些关系需要通过实际源代码验证。

Localized Surface by Page

顶部导航

顶部导航包含以下标签：

中文标签	English 对应内容的范围	页面职责
分析	分析主功能	上传文档并进行分析
存档	历史记录	查看历史分析记录
发现	版本更新	查看版本更新与发布记录
关于	项目信息	查看版本、简介、功能和帮助
设置	应用配置	配置模型、外观和通用设置

具体英文翻译文本没有在现有材料中逐项列出，因此本文只确认存在 English 界面，不补写未经证实的翻译字符串。

分析页面

分析页是 OneDocs 的核心功能区域，采用左侧功能选择栏、中间文件上传区和右侧结果展示区的三栏布局。与本地化相关的文案面包括：

四种分析模式的名称；
“开始析文”操作按钮；
文件选择或拖拽上传提示；
已上传文件列表及排序提示；
分析结果展示状态；
渲染/源码查看模式；
复制和导出操作。

这些内容是用户在切换语言后最直接可见的界面文本。分析模式的业务语义和分析结果本身不属于本地化机制的实现说明；本文只覆盖它们在界面中的显示文案。

存档页面

存档页采用左右两栏布局：左侧显示历史分析记录列表，包括时间和文件数量；右侧显示选中存档的分析结果，并支持渲染/源码查看。语言切换可能影响列表标题、空状态、时间或文件数量的展示文案，但现有材料没有说明日期、数量格式化或结果内容是否随语言改变。

发现页面

发现页展示 OneDocs 的版本更新记录，左侧为版本列表，右侧为选中版本的更新说明。页面标题、列表空状态、更新说明辅助文案属于界面本地化范围；版本发布内容是否存在多语言版本，现有材料没有说明。

关于页面

关于页包含版本、简介、功能和帮助四个标签：

版本：当前版本号、官网入口、开源仓库、开源协议和技术栈；
简介：OneDocs 项目介绍；
功能：四大分析模式介绍；
帮助：完整的新手使用教程。

该页面同时包含固定界面标签和较长的说明内容。当前材料未说明简介、功能说明和帮助教程是否来自翻译资源、静态 Markdown，还是根据语言动态选择内容，因此不能进一步描述资源加载或回退机制。

设置页面

设置页分为通用、外观和模型三个标签。语言本地化直接涉及标签名、分组标题、选项名称、提示信息和开关状态文案。

通用标签包括语言设置、格式复查、自动保存、数据目录、RAG 嵌入模型配置和开发者模式。外观标签包括主题模式、字体风格、字号大小、背景颜色和背景图片。模型标签包括供应商、API Key、Base URL、模型选择和自定义模型。

其中只有语言设置本身属于本页主题；其他选项是语言切换后需要被翻译的界面表面，但其配置语义和运行逻辑属于对应的功能页面。

User Flow

已确认的用户操作路径可以概括为：用户从顶部导航栏或通用设置进入语言设置，选择中文或 English，随后继续使用各页面。切换后的具体生效时机和保存方式没有源代码证据，因此以下流程只表达界面关系，不声明未验证的内部调用。

用户进入 OneDocs 任一页面。
用户从顶部导航栏访问语言切换，或打开设置页的通用标签。
用户选择中文或 English。
用户继续访问分析、存档、发现、关于或设置页面。
页面显示对应语言的界面文案；实际刷新、状态同步和持久化行为需以实现为准。

Configuration and Persistence

现有界面说明确认了“语言设置”这一用户可见选项，但没有给出配置键、默认语言、存储位置、序列化格式、环境变量、命令行参数或迁移策略。

配置项	类型	默认值	状态
语言设置	未提供	未提供	已确认存在，具体实现未提供
支持语言	枚举范围未提供	未提供	界面说明列出中文和 English
持久化位置	未提供	未提供	Implementation details not found in source
缺失翻译回退策略	未提供	未提供	Implementation details not found in source

因此，部署或测试时不应依据本文猜测语言配置的持久化位置，也不应假定清除数据目录会重置语言，除非实际源码或运行文档明确说明。

Localization Boundaries and Design Considerations

本地化系统至少需要区分两类内容：一类是导航、按钮、标签、提示和空状态等界面固定文案；另一类是关于页简介、功能介绍、帮助教程和版本更新说明等长文本内容。现有材料只确认这些内容存在于相应页面，未确认它们采用相同的资源机制。

从用户体验角度，顶部导航和通用设置提供两个入口时，应保持当前语言状态的一致性；但当前材料没有证明实现已经做到这一点。扩展或修复时，应重点验证：

两个语言入口是否读写同一状态；
切换后当前页面是否立即更新；
页面重新打开后语言是否保持；
所有导航标签和设置标签是否都有中文与英文文本；
长文本内容是否按语言选择对应版本；
文件数量、日期、错误提示和空状态是否存在语言相关格式化；
缺少翻译内容时使用什么回退策略。

这些是实现验证清单，而不是对当前系统行为的断言。

Usage and Verification Guidance

当前提供的材料没有源码片段、翻译资源或测试文件，因此没有可安全引用的代码示例。为避免捏造 API、资源键或调用方式，本文不提供代码示例。

可以通过界面验收以下可观察行为：

在顶部导航栏检查语言入口是否显示中文和 English 两个选项。
在设置页的通用标签检查语言设置是否可见。
切换语言后检查顶部导航的五个标签是否更新。
依次打开分析、存档、发现、关于和设置页，检查标题、按钮、标签及提示文案。
在关于页检查版本、简介、功能和帮助四个标签的显示。
返回顶部导航或通用设置，确认当前语言的显示状态是否一致；若实现要求持久化，还应重启或重新打开界面进行验证。

Failure Modes and Open Questions

以下问题在现有材料中没有实现证据，不能归类为已实现的错误处理行为：

翻译资源缺失时是否回退到中文、English 或显示键名；
不支持的语言值是否被拒绝或自动纠正；
语言配置损坏时是否恢复默认值；
页面切换过程中语言状态是否可能短暂不一致；
长文本或版本说明不存在目标语言时如何处理；
语言变更是否需要重新加载应用；
本地化错误是否记录日志或向用户显示提示。

如果后续补充源码，应优先查找语言状态的定义、导航栏和通用设置的调用点、翻译资源目录、默认语言初始化逻辑以及相关测试，以确认上述行为。

Extension Points

当前材料没有暴露可确认的接口、资源键命名约定、语言注册机制或插件扩展点，因此不能给出具体扩展 API。新增语言时，至少需要根据实际实现检查导航栏、五个主要页面、设置页三个标签、关于页四个标签、分析页操作区以及空状态和错误提示是否覆盖；但具体文件和改动位置必须以源码为准。

Tests

未提供测试文件或测试结果，因此无法确认当前本地化能力的自动化覆盖范围。建议在实际测试体系中分别验证语言选择入口、页面文案切换、两个入口的状态同步、持久化行为、缺失资源回退和长文本页面；这些属于测试建议，不代表仓库中已经存在对应测试。

当前上下文只提供 user-interface.localization 这一文档主题和一份界面概览草稿，没有提供可确认的兄弟文档路径或源码引用地址。因此不生成可能失效的内部链接。

分析页面：应由分析功能相关文档说明。
外观设置：应由主题、字体和背景相关文档说明。
模型设置：应由模型配置相关文档说明。
存档、发现和关于页面：应由各自页面或功能文档说明。