贡献指南#

我们欢迎对 dftt_timecode 的贡献！本指南将帮助您开始贡献。

开始#

  1. 在 GitHub 上 Fork 仓库

  2. 在本地克隆您的 Fork：

    git clone https://github.com/YOUR_USERNAME/dftt_timecode.git
cd dftt_timecode

开发工作流#

设置开发环境#

创建虚拟环境并安装依赖：

uv sync

此命令将：

  • 创建虚拟环境（如果尚不存在）

  • 从 pyproject.toml 安装所有依赖

  • 以可编辑模式安装包

  • 生成/更新 uv.lock 以实现可重现构建

运行测试#

运行所有测试：

uv run pytest

以详细输出运行测试：

uv run pytest -v -s

运行特定测试文件：

uv run pytest test/test_dftt_timecode.py

代码风格#

  • 遵循 PEP 8 规范

  • 使用有意义的变量和函数名

  • 为所有公共函数和类添加文档字符串

  • 保持函数专注和简洁

编写测试#

所有新功能和错误修复都应包含测试：

import pytest
from dftt_timecode import DfttTimecode

def test_new_feature():
    tc = DfttTimecode('01:00:00:00', 'auto', fps=24)
    # Test your feature
    assert tc.some_new_method() == expected_result

文档#

添加新功能时更新文档：

  1. 为代码添加文档字符串

  2. 更新 docs/ 目录中的相关 .rst 文件

  3. 本地构建文档以验证：

    cd docs
uv run make html

贡献翻译#

我们欢迎为文档翻译做出贡献！目前我们支持：

  • 英文（主要语言）

  • 中文（简体）

如何贡献翻译#

向现有语言添加新翻译：

  1. 进入翻译文件目录：

    cd docs/locale/zh_CN/LC_MESSAGES/

  2. 编辑 .po 文件以添加或改进翻译：

    #: ../../quickstart.rst:2
msgid "Quick Start"
msgstr "快速开始"

  3. 构建并预览您的翻译：

    cd docs
uv run make html-zh      # Build Chinese only
uv run make html-all     # Build all languages

  4. 本地预览：

    cd docs/_build/html
python -m http.server 8000
# Visit http://localhost:8000/zh_CN/

添加新语言：

  1. 为您的语言生成翻译文件：

    cd docs
uv run sphinx-intl update -p _build/gettext -l <LANG_CODE>
# e.g., for Japanese: -l ja

  2. 更新 docs/Makefile，在 LANGUAGES 变量中添加新语言

  3. 更新 docs/_static/switcher.json 以添加您的语言选项

  4. 更新 docs/_templates/language-switcher.html 中的语言切换器模板

  5. 翻译 locale/<LANG_CODE>/LC_MESSAGES/ 中的 .po 文件

  6. 构建并测试您的翻译

翻译指南：

  • 用户文档 （安装、快速开始、用户指南）：翻译所有内容

  • API 文档：翻译页面标题和主要描述，但保持技术细节（类名、方法名、参数）为英文

  • 更新日志：翻译章节标题，但保持技术变更条目为英文

  • 代码示例：保持代码和变量名为英文

  • 技术术语：使用一致的翻译（参见 docs/I18N_README.md 中的翻译指南）

当源文件更改时更新翻译：

当文档源文件更新时，需要更新翻译：

cd docs
uv run make gettext        # Generate new translation templates
uv run make update-po      # Update .po files with new strings
# Edit .po files to translate new or updated strings
uv run make html-all       # Rebuild documentation

翻译系统概述

本项目使用 Sphinx 和 sphinx-intl 进行国际化。系统使用 gettext .po （Portable Object）文件进行翻译，这是软件本地化的行业标准。

文件结构：

docs/
├── locale/                      # Translation files directory
│   └── zh_CN/
│       └── LC_MESSAGES/
│           ├── index.po         # Translations for index.rst
│           ├── quickstart.po
│           ├── user_guide.po
│           └── api/
│               ├── dftt_timecode.po
│               ├── dftt_timerange.po
│               └── error.po
├── _build/
│   └── gettext/                 # Generated .pot template files (don't commit)
└── _templates/
    └── language-switcher.html   # Language switcher dropdown widget

详细翻译工作流：

  1. 生成翻译模板 （当源文档更改时）：

    cd docs
uv run make gettext

    这将在 _build/gettext/ 中创建 .pot 文件，包含所有可翻译的字符串。

  2. 更新翻译文件：

    cd docs
uv run make update-po

    这将使用新字符串更新 locale/zh_CN/LC_MESSAGES/ 中的 .po 文件，同时保留现有翻译。

  3. 翻译字符串：

    打开 .po 文件并添加翻译：

    #: ../../index.rst:70
msgid "User Guide"
msgstr "用户指南"

#: ../../index.rst:78
msgid "API Reference"
msgstr "API 参考"

    翻译提示：

    • 每个 msgid 包含原始英文文本

    • 在相应的 msgstr 字段中添加您的翻译

    • 保留格式化代码，如 {0}、%s 等

    • 保持技术术语（类名/函数名）不翻译

    • 使用 Poedit 等工具进行更轻松的编辑

  4. 构建和测试：

    cd docs
uv run make html-zh      # Build Chinese only
uv run make html-all     # Build all languages

    预览结果：

    cd docs/_build/html
python -m http.server 8000
# Visit http://localhost:8000/zh_CN/

  5. 提交您的更改：

    git add locale/
git commit -m "Update Chinese translation for user guide"

重要的 Makefile 命令：

  • make gettext：从源 .rst 文件生成 .pot 模板文件

  • make update-po：从 .pot 模板更新 .po 文件

  • make html：仅构建英文文档

  • make html-zh：仅构建中文文档

  • make html-all：构建所有语言版本

常见问题和解决方案：

翻译未显示：

  1. 确保 .po 文件具有非空的 msgstr 值

  2. 使用 uv run make html-all 重新构建

  3. 清除浏览器缓存或使用隐身模式

新字符串未出现在 .po 文件中：

  1. 运行 uv run make gettext 重新生成 .pot 文件

  2. 运行 uv run make update-po 更新 .po 文件

  3. 检查您的源 .rst 文件是否包含在构建中

语言切换器不工作：

  1. 验证 _templates/language-switcher.html 存在

  2. 确保目标语言 HTML 已构建在正确的子目录中 (_build/html/zh_CN/)

最佳实践：

  • 提交 ``.po`` 文件：始终将更新的 .po 文件提交到版本控制

  • 不要提交 ``.pot`` 文件：这些是 _build/gettext/ 中生成的构建产物

  • 增量翻译：可以提交部分翻译的 .po 文件；未翻译的字符串将显示为英文

  • 推送前审查：推送翻译前在本地构建和预览

  • 一致的术语：在所有页面上对技术术语使用一致的翻译

  • 保持源同步：定期运行 make update-po 以与源更改同步

自动化部署：

当推送到 main 分支时，文档将通过 GitHub Actions 自动构建和部署：

当您将翻译的 .po 文件推送到 main 分支时（通过 dev 合并），多语言文档将自动重新构建和部署。

附加资源：

提交更改#

  1. 为您的更改创建新分支：

    git checkout -b feature/my-new-feature

  2. 进行更改并提交：

    git add .
git commit -m "Add new feature: description"

  3. 推送到您的 Fork：

    git push origin feature/my-new-feature

  4. 在 GitHub 上打开 Pull Request

Pull Request 指南#

  • 提供更改的清晰描述

  • 引用任何相关问题

  • 确保所有测试通过

  • 根据需要更新文档

  • 保持更改集中且原子化

报告错误#

报告错误时，请包含：

  • Python 版本

  • dftt_timecode 版本

  • 能重现问题的最小代码示例

  • 预期行为与实际行为

  • 任何错误消息或堆栈跟踪

功能请求#

欢迎功能请求！请提供：

  • 功能的清晰描述

  • 使用场景和示例

  • 为什么这对其他用户有价值

行为准则#

  • 保持尊重和包容

  • 专注于建设性反馈

  • 帮助为所有贡献者创建一个友好的环境

许可证#

通过贡献，您同意您的贡献将按照 GNU Lesser General Public License v2 (LGPLv2) 授权。