Closing the Localization Loop: Automating Git Sync with Weblate

The Friction of Manual Translation Updates

The traditional localization workflow is often a bottleneck: developers add a feature, export a translation file, send it to a translator, and then manually commit the returned file back into the codebase. This manual hand-off introduces version drift, where the production app uses outdated strings while the translation files live in an email attachment or a separate spreadsheet.

The solution is to treat translation files as living code. By integrating Weblate directly with your Git repository, you move from a "push-pull" manual process to a bidirectional synchronization loop. When a developer pushes a new source string to Git, Weblate detects it; when a translator saves a translation in the UI, Weblate commits it back to the branch.

Mapping Repository Structure to Components

Weblate doesn't just import a folder; it uses a Component architecture. A component is a logical grouping of translation files that share the same template and source. For example, if your project has separate translation files for the web frontend and the Android app, these should be two distinct components.

Each component maps a specific file path in your repository to a translation unit. This allows you to maintain strict control over where files are stored. If your project uses gettext, Weblate looks for .po files; for Android, it targets strings.xml. This mapping ensures that the automated commits generated by Weblate maintain your project's existing directory structure without introducing clutter.

Implementing a Bidirectional Sync Workflow

To set up an automated loop, you need a Git repository with appropriate write permissions for the Weblate service account. The following example demonstrates the configuration logic for a standard gettext project.

Configuration Example: Gettext Integration

Assume you have a repository at [contact removed]:org/project.git with translation files located in locale/.

1. Repository Setup: Create a dedicated SSH key for Weblate and add it as a Deploy Key with write access to the repository.
2. Component Configuration: In the Weblate admin panel, create a new component with these settings:
   • Repository: [contact removed]:org/project.git
   • File Mask: locale/*.po
   • Template File: locale/messages.pot
3. Sync Trigger: Enable "Automatic commit" to ensure changes are pushed to Git immediately upon translation.

Verification Step: To verify the loop, modify a string in the Weblate UI. Then, run the following command on your local development machine to check for the automated commit:

git fetch origin
git log origin/main --grep="Weblate"

You should see a commit message indicating the specific string changed and the user who performed the edit.

Handling Conflicts and Performance

Bidirectional sync introduces the risk of merge conflicts. If a developer modifies a .po file locally while a translator is editing the same string in Weblate, Git will encounter a conflict during the next synchronization.

Weblate handles this via a merge strategy that prioritizes the translation UI for the actual translated strings, but it can still fail if the file structure changes drastically. To mitigate this, it is recommended to restrict direct commits to translation files in your main branch, forcing all translation changes to flow through Weblate.

Technical Limitations

Factor	Impact	Mitigation
Repo Size	Large repositories with thousands of tiny files can slow down the Git index update.	Use specific file masks to limit the scope of the component.
Nested Formats	Deeply nested custom JSON or XML may not map perfectly to flat translation units.	Develop a custom Weblate template to define the parsing logic.
Git Hooks	Strict server-side hooks (e.g., requiring signed commits) may block Weblate's pushes.	Configure bypass rules for the Weblate service account.

Maintaining the Pipeline

The most common failure point in this setup is permission drift. If the SSH key expires or repository permissions change, Weblate will fail to commit, but the UI will still allow translations to be saved internally. This creates a "silent failure" where the UI looks correct, but the code is outdated.

To prevent this, regularly check the Component History and Admin Logs in Weblate. If the "Last synchronized" timestamp is lagging behind the "Last edited" timestamp, investigate the Git connectivity immediately.