Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
332 lines (234 loc) · 9.74 KB

CONTRIBUTING.md

File metadata and controls

332 lines (234 loc) · 9.74 KB

参与 Co-op Translator 项目贡献

本项目欢迎贡献和建议。大多数贡献需要您同意一份贡献者许可协议（CLA），声明您有权利且确实授予我们使用您贡献内容的权利。详情请访问 https://cla.opensource.microsoft.com。

当您提交拉取请求时，CLA 机器人会自动判断您是否需要提供 CLA，并相应地标注 PR（例如状态检查、评论）。只需按照机器人提供的指示操作即可。您只需在所有使用我们 CLA 的仓库中完成一次此操作。

开发环境搭建

建议使用 Poetry 来管理本项目的依赖。我们使用 pyproject.toml 管理项目依赖，因此安装依赖时应使用 Poetry。

创建虚拟环境

使用 pip

python -m venv .venv

使用 Poetry

poetry init

激活虚拟环境

适用于 pip 和 Poetry

  • Windows：

    .venv\Scripts\activate.bat

  • Mac/Linux：

    source .venv/bin/activate

使用 Poetry

poetry shell

安装包及所需依赖

使用 Poetry（根据 pyproject.toml）

poetry install

手动测试

在提交 PR 之前，务必使用真实文档测试翻译功能：

  1. 在根目录创建一个测试目录：

    mkdir test_docs

  2. 将你想翻译的部分 Markdown 文档和图片复制到测试目录。例如：

    cp /path/to/your/docs/*.md test_docs/
cp /path/to/your/images/*.png test_docs/

  3. 本地安装包：

    pip install -e .

  4. 在测试文档上运行 Co-op Translator：

    python -m co_op_translator --language-codes ko --root-dir test_docs

  5. 检查 test_docs/translations 和 test_docs/translated_images 中的翻译文件，确认：

    • 翻译质量
    • 元数据注释正确
    • 保持原始 Markdown 结构
    • 链接和图片正常显示

此手动测试有助于确保您的修改在实际场景中表现良好。

环境变量

  1. 通过复制提供的 .env.template 文件，在根目录创建 .env 文件。
  2. 按照指引填写环境变量。

Tip

额外的开发环境选项

除了本地运行项目外，您还可以使用 GitHub Codespaces 或 VS Code Dev Containers 作为替代的开发环境。

GitHub Codespaces

您可以通过 GitHub Codespaces 虚拟运行示例，无需额外设置。

点击按钮将在浏览器中打开基于 Web 的 VS Code 实例：

  1. 打开模板（可能需要几分钟）：

    Open in GitHub Codespaces

使用 VS Code Dev Containers 本地运行

⚠️ 此选项仅在您的 Docker Desktop 分配了至少 16 GB 内存时有效。如果内存不足 16 GB，您可以尝试 GitHub Codespaces 选项 或 本地搭建。

相关选项是 VS Code Dev Containers，它会使用 Dev Containers 扩展 在本地 VS Code 中打开项目：

  1. 启动 Docker Desktop（如果未安装请先安装）

  2. 打开项目：

    Open in Dev Containers

代码风格

我们使用 Black 作为 Python 代码格式化工具，以保持项目代码风格一致。Black 是一款严格的代码格式化工具，会自动将 Python 代码格式化为符合 Black 风格的样式。

配置

Black 的配置在我们的 pyproject.toml 中指定：

[tool.black]
line-length = 88
target-version = ['py310']
include = '\.pyi?$'

安装 Black

您可以通过 Poetry（推荐）或 pip 安装 Black：

使用 Poetry

设置开发环境时会自动安装 Black：

poetry install
使用 pip

如果使用 pip，可以直接安装 Black：

pip install black

使用 Black

使用 Poetry

  1. 格式化项目中所有 Python 文件：

    poetry run black .

  2. 格式化指定文件或目录：

    poetry run black path/to/file_or_directory
使用 pip

  1. 格式化项目中所有 Python 文件：

    black .

  2. 格式化指定文件或目录：

    black path/to/file_or_directory

Tip

建议配置编辑器在保存时自动使用 Black 格式化代码。大多数现代编辑器通过扩展或插件支持此功能。

运行 Co-op Translator

使用 Poetry 运行 Co-op Translator，请按以下步骤操作：

  1. 进入您想进行翻译测试的目录，或新建一个临时文件夹用于测试。

  2. 执行以下命令。将 -l ko 替换为您想翻译成的语言代码。-d 参数表示调试模式。

    poetry run co-op-translator translate -l ko -d

Note

运行命令前请确保已激活 Poetry 环境（poetry shell）。

贡献新语言支持

欢迎贡献新语言支持。提交 PR 前，请完成以下步骤以确保顺利审核。

  1. 添加语言到字体映射

    • 编辑 src/co_op_translator/fonts/font_language_mappings.yml
    • 添加条目，包含：
      • code：类似 ISO 的语言代码（例如 vi）
      • name：友好的显示名称
      • font：src/co_op_translator/fonts/ 中支持该文字脚本的字体文件
      • rtl：如果是从右向左书写则为 true，否则为 false

  2. 包含所需字体文件（如有）

    • 如果需要新字体，请确认其许可证允许开源分发
    • 将字体文件添加到 src/co_op_translator/fonts/

  3. 本地验证

    • 对小样本（Markdown、图片、笔记本等）运行翻译
    • 确认输出正确渲染，包括字体和 RTL 布局（如适用）

  4. 更新文档

    • 确保语言出现在 getting_started/supported-languages.md
    • 无需修改 getting_started/README_languages_template.md，它由支持列表自动生成

  5. 提交 PR

    • 描述新增语言及字体/许可证相关事项
    • 如可能，附上渲染效果截图

示例 YAML 条目：

new_lang(code):
  name: "New Language"
  font: "NotoSans-Medium.ttf"
  rtl: false

测试新语言

您可以通过以下命令测试新语言：

# 创建并激活虚拟环境
python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate
# 安装开发包
pip install -e .
# 运行翻译
translate -l "new_lang"

维护者指南

提交信息和合并策略

为确保项目提交历史清晰一致，我们在使用 Squash and Merge 策略时，要求最终提交信息遵循特定格式。

当拉取请求（PR）合并时，所有提交会被压缩成一个提交。最终提交信息应遵循以下格式，以保持历史整洁。

提交信息格式（适用于 squash and merge）

提交信息格式如下：

<type>: <description> (#<PR编号>)

  • type：提交类别。我们使用以下类型：

    • Docs：文档更新。
    • Build：构建系统或依赖相关变更，包括配置文件、CI 工作流或 Dockerfile 更新。
    • Core：项目核心功能或特性修改，特别是涉及 src/co_op_translator/core 目录的文件。

  • description：简洁的变更摘要。

  • PR number：关联的拉取请求编号。

示例：

  • Docs: Update installation instructions for clarity (#50)
  • Core: Improve handling of image translation (#60)

Note

目前，Docs、Core 和 Build 前缀会根据修改的源代码标签自动添加到 PR 标题。只要标签正确，通常无需手动修改 PR 标题。只需确认前缀生成正确即可。

合并策略

我们默认使用 Squash and Merge 策略合并 PR。此策略确保提交信息符合格式要求，即使单个提交不符合。

原因：

  • 保持项目历史清晰、线性。
  • 提交信息一致。
  • 减少琐碎提交带来的噪音（如“修正拼写错误”）。

合并时，请确保最终提交信息符合上述格式。

Squash and Merge 示例

如果 PR 包含以下提交：

  • fix typo
  • update README
  • adjust formatting

合并后应为： Docs: Improve documentation clarity and formatting (#65)

发布流程

本节介绍维护者发布 Co-op Translator 新版本的最简流程。

1. 在 pyproject.toml 中更新版本号

  1. 确定下一个版本号（遵循语义化版本号：MAJOR.MINOR.PATCH）。
  2. 编辑 pyproject.toml，更新 [tool.poetry] 下的 version 字段。
  3. 提交一个专门修改版本号（及自动更新的锁文件/元数据文件，如有）的 PR。
  4. 审核通过后，使用 Squash and Merge，确保最终提交信息符合上述格式。

2. 创建 GitHub Release

  1. 进入 GitHub 仓库页面，打开 Releases → Draft a new release。
  2. 从 main 分支创建新标签（例如 v0.13.0）。
  3. 设置发布标题为版本号（例如 v0.13.0）。
  4. 点击 Generate release notes 自动生成更新日志。
  5. 可选编辑文本（例如突出新增语言或重要变更）。
  6. 发布该版本。

免责声明：
本文件由人工智能翻译服务 Co-op Translator 翻译而成。尽管我们力求准确，但请注意自动翻译可能存在错误或不准确之处。原始文件的母语版本应被视为权威来源。对于重要信息，建议采用专业人工翻译。我们不对因使用本翻译而产生的任何误解或误释承担责任。