Read the Docs项目中翻译列表显示问题的分析与修复

Read the Docs是一个流行的开源文档托管平台，它支持多语言文档的构建和托管。在使用过程中，开发团队发现了一个关于项目翻译列表显示的问题，这个问题影响了用户在多语言文档间切换的体验。

问题背景

在Read the Docs的实现中，每个项目可以有一个主语言项目和多个翻译项目。当用户访问某个语言的文档时，系统会通过project.translations字段返回所有可用的翻译列表，以便用户可以在不同语言版本间切换。

然而，当前的实现存在两个主要问题：

1. 当用户访问某个翻译版本时，系统仍然会返回当前正在访问的翻译版本
2. 当用户访问翻译版本时，系统没有返回主语言项目作为可选翻译

问题影响

这种实现方式会导致以下不良用户体验：

• 翻译列表中会出现重复项（当前访问的语言版本）
• 用户无法直接从翻译版本切换回主语言版本
• 界面显示混乱，不符合用户预期

技术分析

问题的根源在于readthedocs/proxito/views/hosting.py文件中的AddonsResponse类实现。当前代码简单地获取主项目的所有翻译，但没有考虑当前访问的项目是否是翻译项目，也没有正确处理主项目与翻译项目之间的关系。

解决方案

经过分析，开发团队提出了以下修复方案：

1. 首先排除当前项目本身，确保不会在翻译列表中返回当前访问的项目
2. 如果当前项目是翻译项目，则将主项目添加到翻译列表中
3. 保持翻译列表按语言代码排序

具体实现是通过修改查询集来实现的：

• 使用exclude()方法过滤掉当前项目
• 使用条件判断和查询集合并操作(|=)来包含主项目

实现细节

修复后的代码逻辑更加清晰：

• 明确区分主项目和翻译项目
• 正确处理主项目与翻译项目之间的关系
• 确保翻译列表的完整性和准确性

测试验证

开发团队在本地测试了修复方案，确认了以下行为符合预期：

• 当访问主语言项目时，翻译列表显示所有翻译项目
• 当访问翻译项目时，翻译列表显示主项目和其他翻译项目
• 不会出现重复的翻译项目

总结

这个修复解决了Read the Docs平台中翻译列表显示的核心问题，提升了多语言文档浏览体验。通过正确处理项目间的关系和过滤逻辑，确保了翻译列表的准确性和完整性。这种改进对于使用多语言文档的项目尤为重要，为用户提供了更清晰、更一致的界面体验。