LocalSend 贡献者实战指南：从本地运行、翻译到多平台发布的完整流程（基于 CONTRIBUTING.md）

本文围绕 CONTRIBUTING.md 展开，系统梳理向 LocalSend 这个跨平台 AirDrop 替代品提交贡献的完整路径：如何搭建 Flutter 开发环境并运行源码、如何参与 70+ 种语言的国际化翻译、提交代码与报告 Bug 的规范，以及生产 APK 编译、Flutter 版本升级与发布流程等进阶操作。读完本文后，你可以独立完成 LocalSend 的本地构建与运行，并规范地提交翻译、代码或参与新分发渠道的维护。

贡献政策与 AI 生成内容的边界

LocalSend 是开源项目，欢迎开发者、翻译者和文档作者参与。但文档在开头明确了一条政策：除非满足以下条件之一，否则不接受 AI 生成的贡献：

• 是 Bug 修复；
• 改动非常小；
• 你能够在 PR 中证明自己在该领域的专业水平。

这条政策提醒贡献者：提交前需能说明改动依据，尤其是涉及 Rust 网络协议层或 Flutter UI 的核心代码时。

本地运行：三步命令启动应用

文档给出的启动流程非常简洁。安装 Flutter 后，在仓库根目录依次执行：

cd app
flutter pub get
dart run build_runner build -d
flutter run

结合仓库实际配置，可以进一步理解每一步的作用与前提：

• Flutter 版本要求：app/pubspec.yaml 中声明 flutter: ^3.41.0、Dart sdk: ^3.11.0；各 CI 工作流（如 .github/workflows/ci.yml）统一使用 FLUTTER_VERSION: "3.41.9"，建议本地以 3.41.x 为准。
• Rust 工具链：LocalSend 的传输核心（发现、HTTP 服务器、加密、WebRTC）由 Rust 实现，位于 packages/core 与 packages/localsend_isolates。根目录的 rust-toolchain.toml 固定了 Rust 1.97.1，桌面端编译时会通过 cargo 构建原生库。
• dart run build_runner build -d 的必要性：仓库是 Dart 工作区（见根 pubspec.yaml，workspace 含 app、packages/localsend_isolates、packages/typed_isolates）。app 内大量代码是代码生成的产物：国际化字符串 app/lib/gen/strings.g.dart（由 slang 生成）、数据模型 mapper（*.mapper.dart，由 dart_mappable_builder 生成）等。app/build.yaml 中可以看到 slang_build_runner 等 builder 的完整配置，因此跳过 build_runner 直接运行会因缺少生成代码而编译失败。

参与翻译：i18n 文件的三种修改场景

LocalSend 的界面文本全部来自 app/assets/i18n 目录，每个语言一个 JSON 文件（如 en.json、zh-CN.json），另有 _missing_translations_<locale>.json 列出各语言缺失的词条。文档给出了三种参与方式：

1. 为已有语言补充缺失词条：只修改 _missing_translations_<locale>.json；
2. 修正已有翻译：更新对应的 i18n JSON 文件；
3. 新增语言：新建语言文件，语言代码可参考文档链接的 locale codes 列表。

几个从源码可确认的细节：

• @ 开头的字段不参与翻译。如 en.json 中的 quickSave 下 "off": "@:general.off" 是引用而非文本。文档特别提醒：带 @ 修饰的字段在应用中完全没有使用，只是给翻译者的上下文说明，不要翻译。
• slang 配置：app/build.yaml 显示 slang 以 en 为 base_locale、回退策略为 base_locale、输入目录为 assets/i18n、且关闭了时间戳输出（注释写明是为了 F-Droid 的可复现构建）。因此新语言缺失的词条会回退到英文，不会导致编译失败。
• 重新生成代码：文档给出的可选步骤是修改翻译后在 app 目录执行 flutter pub run slang 再 flutter run；实际等价于运行 build_runner 时由 slang_build_runner 重新生成 app/lib/gen/strings_<locale>.g.dart。
• 测试守护：app/test/unit/i18n_test.dart 包含两项测试——校验 i18n 文件可编译且英文词条存在，以及校验 AppLocale 中每个语言代码都在 Flutter 的 kMaterialSupportedLanguages 支持列表内。这为新增语言提供了硬性约束：所选 locale 必须是 Flutter 支持的语言代码。

完成翻译后 fork 仓库提交 Pull Request 即可。感谢所有翻译者的工作，贡献者名单展示在 app/lib/pages/about/translators.dart 中。

代码贡献规范与问题反馈渠道

代码规范

文档列出的 Pull Request 要求：

• 代码应文档充分，并遵循 Dart Style Guide 格式化；
• 所有改动应配有测试（可参考 app/test/unit 下现有测试的写法）；
• Commit 信息应描述清晰、附带上下文；
• PR 目标分支为 main，并在描述中清晰总结改动。

Bug 报告与功能请求

通过仓库的 issue tracker 提交，需附清晰的描述、相关上下文和复现步骤。仓库提供了结构化模板 .github/ISSUE_TEMPLATE（含 bug_report.yml 与 feature_request.yml），按模板填写能让维护者更快定位问题。

安全问题

发现安全漏洞时不要公开发 issue，应直接邮件联系 [e-mail]，以便在公开前快速修复。

分发渠道现状：Git 包、商店与二进制

文档的 Distribution 一节完整维护着 LocalSend 在各渠道的分发状态，这是贡献者了解"谁在维护哪个包"的权威索引：

Git 包管理渠道（由社区维护者 + CI 协作维护）：

渠道	维护方
Winget	@sitiom、@Tienisto、GitHub Actions
Scoop	@sitiom、@Tienisto、GitHub Actions
Chocolatey	@brogers5
Homebrew	@Tienisto、GitHub Actions
Flathub	@proletarius101、@Tienisto、GitHub Actions
AUR	@Nixuge
Nixpkgs	@sikmir、@linsui
F-Droid	@linsui、@Tienisto、F-Droid CI
Snap	@thatLeaflet

手动发布渠道：App Store、Play Store、Amazon 均由 @Tienisto 维护。

二进制发布：Windows ZIP、MSIX、EXE、APK、TAR、DEB、DMG 由 @Tienisto 维护，AppImage 额外致谢 @TheGB0077。

文档还列出了待办事项，欢迎通过 issue 认领：传统 Linux 发行版仓库（Debian、Fedora 等）的原生打包。相关 CI 入口在 .github/workflows 中，如 build_appimage.yml、build_rpm.yml、release.yml 等，可作为理解各渠道产物的参考。

进阶 Notes：APK 签名、Flutter 升级与发布流程

文档 Notes 一节沉淀了三段维护者级别的实战经验。

编译生产 APK

正式 APK 需要签名密钥。没有密钥时可用 debug 签名顶替，方法是修改 app/android/app/build.gradle：

buildTypes {
  release {
    signingConfig signingConfigs.debug // 使用 debug 签名
  }
}

注意这只是本地/内部验证用途，上架渠道的签名政策见 CODE_SIGNING.md。

升级 Flutter 版本（Bump Flutter）

文档以升级到 3.41.9 为例，给出三步流程：

1. 用 fvm 切换本地版本：fvm use 3.41.9；
2. 更新 Flutter 子模块：
   1. git submodule update --init
   2. cd support/submodules/flutter
   3. git fetch
   4. git checkout 3.41.9
   5. cd ../../..
   6. git add support/submodules/flutter
3. 同步更新版本约束：CI 工作流（.github/workflows/ci.yml 等处的 FLUTTER_VERSION 环境变量）与 app/pubspec.yaml 的 environment 段。

仓库中 support/submodules/flutter 即为该子模块的挂载点。

发布流程（Release）

发布依赖自托管 Runner 编译 arm64 Linux 产物。Runner 需先安装 Flutter：

sudo apt install git
git clone https://github.com/flutter/flutter.git $HOME/flutter

在 ~/.bashrc 末尾追加：

export PATH="$PATH:$HOME/flutter/bin"

重启终端后执行 flutter doctor 验证，再按 GitHub 指引安装 Runner。随后从 Actions 面板启动 "Release Draft" 工作流（对应 release.yml），最后对流水线尚未覆盖的平台产物手动补编译。

小结

CONTRIBUTING.md 为 LocalSend 贡献者提供了清晰的入口地图：三行命令即可本地运行（前提是满足 app/pubspec.yaml 中的 Flutter 3.41 / Dart 3.11 约束，并留意 rust-toolchain.toml 固定的 Rust 工具链）；翻译贡献以 app/assets/i18n 的 JSON 文件为中心，受 slang 配置与 i18n 单元测试的双重约束；代码贡献要求测试覆盖与规范 PR；而 APK 签名、Flutter 升级与发布流程则完整覆盖了从个人贡献到维护者操作的进阶路径。结合 .github/workflows 与 .github/ISSUE_TEMPLATE 中的实际配置，贡献者可以据此判断自己的改动会在哪个环节被验证。