版本控制集成

Weblate 当前支持 Git (扩展支持 GitHub 拉取请求GitLab 合并请求Gitea 拉取请求GerritSubversionBitbucket 服务器拉取请求Azure DevOps 拉取请求)和 Mercurial 作为版本控制后端。

访问仓库

您要使用的版本控制系统仓库必须可供 Weblate 访问。对于公开可用的仓库,您只需要输入正确的 URL(例如 https://github.com/WeblateOrg/weblate.git),但对于私有仓库或推送 URL,设置更加复杂并且需要验证。

从 Hosted Weblate 访问仓库

Hosted Weblate 在 GitHub、Bitbucket、Codeberg 和 GitLab 上注册有一个专门的推送用户(用户名 weblate、电子邮箱 hosted@weblate.org 以及名称或个人资料描述 Weblate push user)。

提示

这些平台上可以有更多这样的 Weblate 用户,由其他 Weblate 实例所指定。建议搜索电子邮箱 hosted@weblate.org 以找到正确的 Hosted Weblate 推送用户。

您需要将此用户添加为协作者并为其授予对您的仓库的适当权限(克隆可以只读,推送需要写入)。根据服务和您组织的设置,这会立即发生,或者需要在 Weblate 端进行确认。

GitHub 上的 weblate 用户会在五分钟内自动接受邀请。其他服务可能需要人工处理,请耐心等待。

一旦 weblate 用户被添加到你的仓库,你可以使用SSH协议(例如 git@github.com:WeblateOrg/weblate.git)配置 源代码仓库仓库推送 URL

访问代码托管站点(GitHub, GitLab, Bitbucket, Azure DevOps, …)上的仓库

访问代码托管站点上的仓库通常是通过创建和 Weblate SSH 密钥相关联的专门用户实现的(见 Weblate SSH 密钥)。这样做,你将 Weblate SSH 密钥与单一用户相关联(代码平台经常强制这么做)并授予此用户访问仓库的权限。关联后,你可以使用 SSH URL 来访问仓库(见 SSH 仓库)。

提示

在 Hosted Weblate 上,这对多数公开站点是预先配置好的,请见 从 Hosted Weblate 访问仓库

SSH 仓库

访问私有仓库的最常用方法是基于 SSH。授权公共 Weblate SSH 密钥(请参阅 Weblate SSH 密钥)以这种方式访问上游仓库。

警告

在 Github 上,每个密钥只能用一次,见 GitHub 仓库从 Hosted Weblate 访问仓库

Weblate 还会在首次连接时存储主机密钥指纹,并且在以后进行更改时将无法连接到主机(请参阅 验证 SSH 主机密钥)。

如果需要调整,请从 Weblate 管理界面进行:

_images/ssh-keys.webp

Weblate SSH 密钥

在 4.17 版本发生变更: Weblate 现在生成 RSA 和 Ed25519 SSH 密钥。新安装建议使用 Ed25519。

Weblate 公钥对浏览 关于 页面的所有用户可见。

管理员可以在管理界面着陆页的连接部分(从 SSH 密钥)生成或显示 Weblate 当前使用的公共密钥。

备注

相应的 SSH 私钥当前无法使用密码,因此请确保其受到良好的保护。

提示

对生成的私有 Weblate SSH 密钥进行备份。

验证 SSH 主机密钥

Weblate 在第一次访问时自动存储SSH主机密钥,并记住它们以备将来使用。

如果你想在连接到仓库之前验证密钥指纹,在管理界面的同一区域,在 添加主机密钥 中添加你要访问的服务器的SSH主机密钥。输入你要访问的主机名(例如: gitlab.com ),然后点击 提交 。确认其指纹与你添加的服务器相匹配。

添加的带指纹的密钥显示在确认消息中:

_images/ssh-keys-added.webp

连接到旧式 SSH 服务器

最近的 OpenSSH 发行版(比如用于 Weblate Docker 容器中的 OpenSSH) 默认禁用了使用 SHA-1 哈希算法的 RSA 签名。做出此变化是因为 SHA-1 哈希算法存在密码学缺陷,存在以不到 50 K 美元的成本创建指定前缀哈希碰撞的可能性。

多数用户应该不会注意到这一变化,也无需替换 ssh-rsa 密钥。自 7.2 版本起,OpenSSH便已支持 RFC8332 RSA/SHA-256/512 签名,现有的 ssh-rsa 密钥会在可能的地方自动使用更强的算法。

当连接到尚未升级或尚未密切跟踪 SSH 协议改进的旧 SSH 实现时更有可能发生不兼容。到此类服务器的 SSH 连接会失败,错误为:

no matching host key type found. Their offer: ssh-rsa

对于这些情况,可能需要有选择地重新启用 RSA/SHA1 以允许通过 HostkeyAlgorithms 和 PubkeyAcceptedAlgorithms 选项来允许连接和/或用户身份验证。比如,文件 DATA_DIR/ssh/config 中的下列段落会为单一目标主机的主机和用户身份验证启用 RSA/SHA1:

Host legacy-host
   HostkeyAlgorithms +ssh-rsa
   PubkeyAcceptedAlgorithms +ssh-rsa

我们建议将启用 RSA/SHA1 仅作为可以升级旧实现或使用另一密钥类型(比如 ECDSA 或 Ed25519)前的权宜之计。

GitHub 仓库

可以通过 SSH 访问(请参阅 SSH 仓库 ),但如果您需要访问多个仓库,您将遇到 GitHub 对允许使用的 SSH 密钥的限制(因为每个密钥只能使用一次) .

如果 推送分支 未设置,则项目将被分叉并通过分叉推送更改。如果已设置,更改将推送到上游仓库和选择的分支。

对于较小的部署,使用带有个人访问令牌和您的 GitHub 账户的 HTTPS 身份验证,请参阅 创建用于命令行使用的访问令牌

对于更大的设置,通常最好为 Weblate 创建一个专用用户,为其分配在 Weblate 中生成的公共 SSH 密钥(请参阅 Weblate SSH 密钥)并授予它访问您要翻译的所有仓库的权限。这种方法也用于 Hosted Weblate,有专门的 weblate 用户。

Weblate 内部网址

通过在其他(链接)组件中将其位置称为“weblate://project/component”,在不同组件之间共享一个仓库设置。这样,链接的组件使用主(引用)组件的版本控制系统仓库配置。

警告

删除主部件也会删除链接的部件。

如果 Weblate 找到具有匹配的仓库设置的部件,则在创建组件时会自动调整仓库 URL。您可以在部件配置的最后一步中覆盖它。

使用这个的原因:

  • 为了节省服务器上的磁盘空间,仓库仅存储一次。

  • 为了使更新更快,只更新一个仓库。

  • 只有一个带有 Weblate 翻译的导出仓库(参见 Git 导出器 )。

  • 一些附加组件可以在共享一个仓库的多个组件上运行,例如 挤压 Git 提交

HTTPS 仓库

要访问受保护的 HTTPS 仓库,请在 URL 中包含用户名和密码。不用担心,当 URL 显示给用户时,Weblate 会删除此信息(如果甚至允许查看仓库 URL)。

例如,添加了身份验证的 GitHub URL 可能如下所示:https://user:your_access_token@github.com/WeblateOrg/weblate.git

备注

如果你的用户名和密码包含特殊字符,需要对URL进行encode编码,例如 https://user%40example.com:%24password%23@bitbucket.org/…

使用代理

如果需要使用代理服务器访问 HTTP/HTTPS VCS 仓库,请将 VCS 配置为使用它。

这可以使用 http_proxyhttps_proxyall_proxy 环境变量来完成(如 cURL 文档 中所述)或通过在版本控制系统配置中强制执行,例如:

git config --global http.proxy http://user:password@proxy.example.com:80

备注

代理配置需要在运行 Weblate 的用户下完成(参见 文件系统权限 )并使用 HOME=$DATA_DIR/home (参见 DATA_DIR ),否则由 Weblate 执行 Git 不会使用它。

Git

提示

Weblate 需要 Git 2.12 或更新版本。

参见

有关如何访问不同类型的仓库的信息,请参阅 访问仓库

Git 强制推送

这与 Git 本身的行为完全一样,唯一的区别是它总是强制推送。这仅适用于使用单独的翻译仓库的情况。

警告

请谨慎使用,因为这很容易导致上游仓库中的提交丢失。

自定义 Git 配置

Weblate 使用 HOME=$DATA_DIR/home 调用所有 VCS 命令(请参阅 DATA_DIR),因此需要在 DATA_DIR/home/.git 中完成编辑用户配置。

Git 远程帮助程序

您还可以使用 Git 远程帮助程序 来额外支持其他版本控制系统,但要准备好调试这可能导致的问题。

目前,Bazaar 和 Mercurial 的助手可在 GitHub 上的单独仓库中使用:git-remote-hggit-remote-bzr 。手动下载它们并将它们放在搜索路径中的某个位置(例如 ~/bin )。确保您安装了相应的版本控制系统。

一旦你安装了这些,这些远程可以用来在 Weblate 中指定一个仓库。

使用 Bazaar 从 Launchpad 克隆 gnuhello 项目:

bzr::lp:gnuhello

对于来自 selenic.com 的 hello 仓库使用 Mercurial:

hg::http://selenic.com/repo/hello

警告

使用 Git 远程助手的不便之处在于 Mercurial,远程帮助程序有时会在推送更改时创建新的提示。

GitHub 拉取请求

这在 Git 顶部添加了一个薄层,使用 GitHub API 允许将翻译更改作为拉取请求推送,而不是直接推送到仓库。

Git 将更改直接推送到仓库,而 GitHub 拉取请求 创建拉取请求。仅访问 Git 仓库不需要后者。

您需要在 Weblate 设置中配置 API 凭据 (GITHUB_CREDENTIALS) 才能使其工作。配置完成后,您将在选择 版本控制系统 时看到 GitHub 选项。

GitLab 合并请求

这只是使用 GitLab APIGit 上添加了一个薄层,以允许将翻译更改作为合并请求推送,而不是直接推送到仓库。

不需要使用它来访问 Git 仓库,普通的 Git 工作方式相同,唯一的区别是如何处理推送到仓库。使用 Git 将更改直接推送到仓库,而 GitLab 合并请求 创建合并请求。

您需要在 Weblate 设置中配置 API 凭据 (GITLAB_CREDENTIALS) 才能使其工作。配置完成后,您将在选择 版本控制系统 时看到 GitLab 选项。

Gitea 拉取请求

Added in version 4.12.

这只是使用 Gitea APIGit 上添加了一个薄层,以允许将翻译更改作为拉取请求推送,而不是直接推送到仓库。

不需要使用它来访问 Git 仓库,普通的 Git 工作方式相同,唯一的区别是如何处理推送到仓库。使用 Git 将更改直接推送到仓库,而 Gitea 拉取请求 创建拉取请求。

您需要在 Weblate 设置中配置 API 凭据 (GITEA_CREDENTIALS) 才能使其工作。配置完成后,您将在选择 版本控制系统 时看到 Gitea 选项。

Bitbucket 服务器拉取请求

Added in version 4.16.

这只是使用 Bitbucket Server APIGit 上添加了一个薄层,以允许将翻译更改作为拉取请求推送,而不是直接推送到仓库。

警告

这不支持 Bitbucket Cloud API。

不需要使用它来访问 Git 仓库,普通的 Git 工作方式相同,唯一的区别是如何处理推送到仓库。使用 Git 将更改直接推送到仓库,而 Bitbucket 服务器拉取请求 创建拉取请求。

您需要在 Weblate 设置中配置 API 凭据 (BITBUCKETSERVER_CREDENTIALS) 才能使其工作。配置完成后,您将在选择 版本控制系统 时看到 Bitbucket Server 选项。

Pagure 合并请求

Added in version 4.3.2.

这只是使用 Pagure APIGit 上添加了一个薄层,以允许将翻译更改作为合并请求推送,而不是直接推送到仓库。

不需要使用它来访问 Git 仓库,普通的 Git 工作方式相同,唯一的区别是如何处理推送到仓库。使用 Git 将更改直接推送到仓库,而 Pagure 合并请求 创建合并请求。

您需要在 Weblate 设置中配置 API 凭据 (PAGURE_CREDENTIALS) 才能使其工作。配置完成后,您将在选择 版本控制系统 时看到 Pagure 选项。

Gerrit

使用 git-review 工具在 Git 上添加一个薄层,以允许将翻译更改作为 Gerrit 审查请求推送,而不是将它们直接推送到仓库。

Gerrit 文档详细介绍了设置此类仓库所需的配置。

Azure DevOps 拉取请求

这在 Git 顶部添加了一个薄层,使用 Azure DevOps API 允许将翻译更改作为拉取请求推送,而不是直接推送到仓库。

Git 将更改直接推送到仓库,而 Azure DevOps 拉取请求 创建拉取请求。仅访问 Git 仓库不需要后者。

您需要在 Weblate 设置中配置 API 凭据 (AZURE_DEVOPS_CREDENTIALS) 才能使其工作。配置完成后,您将在选择 版本控制系统 时看到 Azure DevOps 选项。

Mercurial

Mercurial 是另一个可以在 Weblate 中直接使用的版本控制系统。

备注

它应该适用于任何 Mercurial 版本,但有时对命令行界面的不兼容更改会破坏 Weblate 集成。

参见

有关如何访问不同类型的仓库的信息,请参阅 访问仓库

Subversion

Weblate 使用 git-svnsubversion 仓库交互。它是一个 Perl 脚本,允许 Git 客户端使用 subversion,使用户能够维护内部仓库的完整克隆并在本地提交。

备注

Weblate 尝试自动检测 Subversion 仓库布局 - 它支持分支的直接 URL 或具有标准布局的仓库(分支/、标签/和主干/)。有关这方面的更多信息,请参阅 git-svn 文档 。如果您的仓库没有标准布局并且遇到错误,请尝试在仓库 URL 中包含分支名称并将分支留空。

Subversion 凭据

Weblate 希望您预先接受证书(如果需要,还需要您的凭据)。它会将它们插入到 DATA_DIR 目录中。在 $HOME 环境变量设置为 DATA_DIR 的情况下使用 svn 接受证书:

# Use DATA_DIR as configured in Weblate settings.py, it is /app/data in the Docker
HOME=${DATA_DIR}/home svn co https://svn.example.com/example

参见

DATA_DIR

本地文件

提示

下面,它使用 Git。它需要安装 Git,并允许您切换到本机使用 Git,并提供完整的翻译历史记录。

Weblate 也可以在没有远程 VCS 的情况下运行。初始翻译是通过上传来导入的。稍后您可以通过文件上传替换单个文件,或直接从 Weblate 添加翻译字符串(目前仅适用于单语翻译)。

在后台 Weblate 为您创建一个 Git 仓库并跟踪所有更改。如果您以后决定使用 版本控制系统来存储翻译,您已经在 Weblate 中有一个仓库可以作为您的集成的基础。