Architecting Weblate’s Pull‑Request Workflow for Translation Updates

Problem Statement

When a translation project is managed in Weblate, developers often want the changes to flow back into the source code repository through the familiar pull‑request (PR) channel. This keeps audit trails, leverages existing CI checks, and lets project maintainers review translations before they hit production. However, enabling this flow in a single‑tenant deployment requires careful design around Git access, token handling, and failure recovery.

Requirements

• Git hosting – A remote repository (GitHub, GitLab, Bitbucket, etc.) that supports API‑based PR creation and status checks.
• Weblate project – Configured to push translation files to the remote repo.
• Access token – Scoped to the repository with write and pull‑request (or equivalent) permissions.
• Branch protection (optional) – Enforces PR reviews before merge.
• Weblate PR integration hook – Built‑in feature that triggers PR creation after a push.

Minimal Design

1. Local storage – Weblate holds translation strings in its PostgreSQL database.
2. Push to remote – On a commit event, Weblate creates a temporary branch in the remote repo and pushes the updated files.
3. PR creation – Using the provider’s REST API, Weblate submits a PR from the temporary branch to the target branch.
4. CI integration – The remote CI system runs tests on the PR; success triggers an automated merge, otherwise the PR remains open.
5. Pull back – Once merged, Weblate pulls the updated translation files back into its database to keep the local state in sync.

Configuration Example

# In Weblate project settings (UI or settings file)
# Git repository URL
git_url = "https://github.com/example/project.git"
# Branch to push to
branch = "translations"
# Create PR on push
push_mode = "pr"
# Token stored in environment variable
token = "$WEBLATE_GITHUB_TOKEN"

In the GitHub repository, create a personal access token with repo scope and store it in a secure vault. Export the token to the environment variable used by Weblate.

Trust and Data Boundaries

Component	Data Stored	Trust Level
Weblate Database	Translation strings, user metadata	High – internal, only Weblate services access
Git Repository	Source code, .po/.pot files	Medium – accessible by Weblate via token, but also by developers
API Token	Write & PR scopes	Critical – must be stored encrypted and rotated
CI System	Build artifacts, test results	Low – only for automated merge decision

Weblate must validate incoming PRs to guard against malicious file injection. A simple check is to compare the path of changed files against the expected translation file pattern (*/LC_MESSAGES/*.po). Any deviation should abort the merge and alert the administrator.

Operational Checks

• Remote reachability – Run git ls-remote $git_url from the Weblate host; a non‑zero exit code indicates network or credential issues.
• Token validation – Use the provider’s introspection endpoint (e.g., curl -H "Authorization: token $TOKEN" https://api.github.com/user) to confirm the token is active and has the required scopes.
• Webhook monitoring – Configure a webhook on the Git provider to notify Weblate of PR status changes. Verify that the webhook endpoint is reachable and that the payload contains the expected state field.
• Audit logging – Enable Weblate’s Action Log to capture PR creation, merge, and rollback events. Periodically review the log for unexpected failures.

Failure Modes and Mitigations

1. Network partition – If the PR creation request times out, Weblate retries with exponential backoff. After three failures, it logs the error and marks the translation as pending until the network recovers.
2. Permission error – A 403 response from the API triggers an immediate alert. Weblate does not attempt further pushes until the token is refreshed.
3. Merge conflict – If the PR cannot be merged automatically, Weblate updates the PR title to indicate a conflict and stops the automated merge. An administrator must resolve the conflict manually.
4. Token revocation – If the token becomes invalid, Weblate stops creating PRs and logs a critical error. An alert is sent to the DevOps team.

Conditions That Alter the Design

• Self‑hosted Git server – Without a public API, the design must fall back to using git push to a protected branch and rely on manual PR creation.
• Mandatory code review – Enable branch protection rules that require at least one approving review before merge. Weblate must then expose a review status indicator in its UI.
• Regulatory audit requirements – Store every translation change in a separate immutable audit log (e.g., using a write‑once storage service) and reference the audit ID in the PR description.
• Multi‑tenant scaling – Each tenant would need its own repository and token. The architecture would shift to a dynamic token manager that issues tenant‑specific tokens on demand.

Practical Verification Steps

1. Create a test translation change in Weblate and observe that a PR is created in the remote repo.
2. In the remote repo, verify the PR contains only the expected .po files and that the commit message matches the Weblate change description.
3. Trigger a CI run that passes; confirm that Weblate auto‑merges the PR.
4. After merge, ensure Weblate pulls the updated files back and the database reflects the new translations.
5. Revoke the token, repeat step 1, and confirm that Weblate logs an error and does not create a PR.

Conclusion

By treating Weblate as the single source of truth for translations and orchestrating a PR‑based synchronization with the code repository, teams can benefit from familiar review workflows, automated CI checks, and a clear audit trail. The minimal design outlined above balances simplicity with security, but be prepared to adjust the architecture if your environment evolves—especially when moving to self‑hosted Git services or scaling to multiple tenants.