Automating Translation Sync with Weblate Continuous Integration

The Synchronization Gap

Managing translations manually between a codebase and a translation platform often leads to "version drift," where the developers' source files and the translators' work diverge. The goal is to establish a bidirectional pipeline where Weblate automatically pulls new source strings from Git and pushes completed translations back to the repository without manual intervention.

Prerequisites

• A running Weblate instance (v4.0+ recommended).
• A Git repository (GitHub, GitLab, or Bitbucket) containing your translation files (e.g., .po, .json, .yaml).
• An SSH key pair or Personal Access Token (PAT) with write access to the target repository.
• Administrative access to the Weblate project settings.

Step 1: Establishing the Git Connection

Weblate requires a secure handshake with your version control system to perform push/pull operations. Using an SSH key is the most stable method for long-term CI automation.

1. Navigate to Account → SSH Keys and add your public key, or configure the global Git provider settings in the Weblate admin panel.
2. When creating a new Component, provide the full SSH clone URL (e.g., [contact removed]:user/repo.git).
3. Specify the Branch (e.g., main or translations). It is strongly recommended to use a dedicated translations branch to avoid cluttering the primary development history with automated commit messages.

Step 2: Mapping Component File Patterns

Weblate uses file patterns to identify which files in the repository belong to which language. Incorrect patterns can result in Weblate ignoring files or, in worst-case scenarios, attempting to overwrite unrelated files.

In the Component settings, configure the File mask. For a standard GNU gettext setup, use a pattern like this:

locale/%(language)s/LC_MESSAGES/messages.po

The %(language)s placeholder is dynamically replaced by the language code (e.g., fr, de) during the sync process.

Step 3: Configuring CI Push Behavior

To automate the flow from Weblate back to Git, you must define the trigger for commits. You can find these under the Component → Settings tab.

• Commit on every change: Pushes a commit every time a translator saves a string. This provides real-time updates but creates a noisy Git history.
• Commit when translation is complete: Pushes only when a translation unit is marked as "translated." This is the preferred balance for most engineering teams.
• Scheduled commits: Pushes changes at a defined interval (e.g., every 24 hours), reducing the number of commits.

Comparison: Push Strategies

Strategy	Git History Impact	Developer Experience	Best Use Case
Per-change	Very High (Noisy)	Instant updates	Small teams, rapid prototyping
On Completion	Moderate	Clean milestones	Standard production apps
Scheduled	Low	Batch updates	Large-scale enterprise projects

Verification and Diagnostics

To ensure the CI pipeline is functioning, perform these three checks in order:

1. Connection Check: Go to the Component settings page. If the repository is unreachable, Weblate will display a connection error immediately.
2. Manual Pull: Trigger a manual update via the Update button in the UI. Check the Weblate logs to confirm a successful git fetch and git merge.
3. End-to-End Push: Edit a single string in the Weblate editor and mark it as translated. Check your remote Git repository's commit history for a commit authored by "Weblate."

Limitations and Risks

• Timeout Risk: For repositories with thousands of translation files, the synchronization process may time out. In these cases, split the project into multiple smaller Components.
• Merge Conflicts: If developers manually edit translation files in the repo while Weblate is pushing changes, Git merge conflicts will occur. Weblate generally handles this by attempting a merge, but complex conflicts may require manual resolution in the repository.

Rollback Procedure

If the CI configuration causes unintended file deletions or repository corruption:

1. Immediately disable the Automatic push setting in the Component configuration to stop further commits.
2. Use git revert [commit_id] or git reset --hard [last_known_good_sha] on your local machine and push to the remote to restore the files.
3. Correct the File mask pattern in Weblate before re-enabling synchronization.