Automating Translation Workflows with Weblate Git Synchronization

The Problem: Translation Drift

When translation files are managed manually between a localization platform and a source code repository, "translation drift" occurs. This happens when developers update strings in the code but the localization team is unaware, or when translators update strings in a UI but those changes never reach the production codebase. This results in missing translations, broken UI layouts, or outdated terminology in live releases.

The solution is to configure Weblate as a bidirectional bridge, treating your Git repository as the single source of truth. By automating the push and pull cycles, you ensure that every translation commit is tracked via version control and every code change is immediately available for translation.

Prerequisites

• Weblate Instance: A running installation of Weblate (version 4.0+ recommended).
• Git Repository: A repository (GitHub, GitLab, Bitbucket, etc.) containing your translation files (e.g., .po, .ftl, or strings.xml).
• SSH Key or Personal Access Token: A credential with write access to the repository. Weblate must be able to push commits back to the branch.
• Celery Worker: A configured task runner (Celery) to handle the asynchronous synchronization tasks.

Configuring the Synchronization Pipeline

Synchronization in Weblate is not a single toggle but a combination of component settings and background task scheduling.

1. Connecting the Repository

Navigate to Components → [Your Component] → Settings. In the Repository section, define the following:

• Repository URL: The SSH or HTTPS URL of your Git repo.
• Branch: The specific branch (e.g., main or i18n-translations) where translation files reside.
• File Mask: A regex or glob pattern to identify translation files (e.g., locales/*.po).

2. Setting the Synchronization Trigger

Weblate can sync changes based on two primary triggers. You must decide which fits your workflow:

To enable automatic pushes, ensure the "Push changes to the repository" option is checked in the component settings. This tells Weblate to create a Git commit whenever a translation is marked as "translated" or a batch of changes is saved.

3. Handling File Formats

Weblate parses files into a database for editing and serializes them back to text for Git. Ensure your File Format is correctly identified (e.g., Gettext for .po files). If the format is mismatched, the synchronization will fail during the serialization phase, potentially corrupting the file in the repository.

Verification and Diagnostics

To confirm the pipeline is functioning, perform the following checks:

The Push Test

1. Edit a translation string in the Weblate web interface.
2. Mark the string as translated and save.
3. Run the following command on your local machine to check for the new commit:

   git pull origin [branch-name] && git log -n 1

4. Expected Result: A commit authored by Weblate should appear in the log containing the updated string.

The Pull Test

1. Manually edit a translation file in your Git repository and push it to the remote.
2. In Weblate, go to Component → Manage → Update translations.
3. Click "Pull from repository".
4. Expected Result: The Weblate UI should reflect the manual change made in the Git repo.

Diagnostic Logs

If synchronization fails, check the Administration → Logs panel. Look for the following error patterns:

• Permission denied (publickey): The SSH key configured in Weblate does not have write access to the Git repository.
• Timeout exceeded: The translation files are too large for the current Celery worker timeout settings.
• Merge conflict: A developer and a translator modified the same line in the same file.

Managing Merge Conflicts

Because Weblate and developers may edit the same files, conflicts occur. When a git push fails due to a non-fast-forward error, Weblate will flag the component as having a synchronization error.

Resolution Path:

1. Perform a manual git pull on a local development machine.
2. Resolve the conflict using a standard merge tool.
3. Push the resolved file back to the repository.
4. In Weblate, trigger a manual "Pull from repository" to synchronize the database with the resolved version.

Limitations and Risks

• Large Files: Very large translation files can cause memory spikes during the parsing phase. Consider splitting files into smaller modules.
• Commit Noise: If "Push on every change" is enabled, your Git history may become cluttered with hundreds of small commits. To mitigate this, use a dedicated i18n branch and merge it into main periodically.
• State Change: This process changes the state of your remote repository. If the file mask is too broad, Weblate may accidentally overwrite non-translation files. Always test the file mask on a staging branch first.