Add a Git-linked Weblate component for PO files with shared memory

Teams that keep translations in a single Git repository often hit a wall when different apps or modules need different file sets, branches, or release cadences. Weblate’s component model solves this by letting one project share a glossary and translation memory while each component owns its own VCS settings, file mask and branch. The practical outcome is a new component that mirrors PO files from Git into the Weblate editor and pushes translator edits back as commits authored by Weblate.

Why components matter for Git-based PO workflows

A Weblate project is a container for components. A component defines where to read translations from, which files to include, and how changes are written back. Keeping components separate avoids a loose file mask that pulls the whole repo and prevents merge conflicts between unrelated modules. The project level still provides shared translation memory and glossary, so terminology stays consistent across components.

Translation memory in Weblate stores previously approved translations and reuses them as suggestions. The file mask is a glob pattern that selects which files Weblate monitors, e.g. locale/*/LC_MESSAGES/messages.po. VCS means version control system, in this case Git.

Prerequisites

• A running Weblate instance version 4.15 or newer with admin access.
• A Git repository reachable via HTTPS or SSH that contains gettext PO files.
• Push permissions for the Weblate system user on that repository. Without push rights automatic commits will fail silently.
• A known source language and a clear file mask that limits the pull to translation files only.

Large repositories or broad masks cause slow initial pulls. Tune the mask to the exact paths you want to translate.

Create the project and component

Add the project

Log in as admin and open Projects → Add project. Fill in a human readable name and optional description. The project slug is used in URLs, so keep it stable. Save. At this stage no files are imported yet.

Configure the component VCS and file mask

Inside the project choose Add component. Set Repository to Git. Enter the repository URL using a placeholder like https://github.com/ORG/REPO.git or an SSH URL. Specify the branch you want Weblate to track, typically main or master.

Set the file mask to match PO files only. A concrete example for Django style layouts is:

locale/*/LC_MESSAGES/messages.po

This mask selects messages.po for each language under locale. Avoid masks like locale/** that also match .pot or unrelated files.

Set the source language, e.g. en. Weblate uses this to identify the reference strings.

Memory and suggestions

Enable the built-in translation memory for the project. This is on by default at project level and applies to all components. Optional machine translation suggestions can be enabled per component if you have a provider configured.

Save the component and trigger an initial repository pull from the component’s Actions menu. Weblate clones the repo into its data directory and parses the files matching the mask.

Verify the link is live

Open the component’s Files list and confirm the expected PO files appear with correct paths. The file count should match the mask.

Open a translation unit in the Weblate editor, make a minor change to a string, and save. With automatic push enabled, Weblate stages the change and creates a commit. Check the repository hosting service for a new commit authored by Weblate containing the updated PO file.

Open Project → Translation memory and search for the string you just changed. After the commit the TM should contain the new entry. This confirms the round-trip from UI to Git to memory.

A useful safety check is to temporarily disable VCS push in Component → Settings → Version control, make another edit, and confirm no commit is generated. Re-enable push and push pending changes manually to verify recovery works.

Recovery, limits and operational notes

If the component fails to sync, open Component → Settings → Version control and use Reset repository to force a fresh clone. You can also re-run Pull and Push from the Actions menu. Reverting the component configuration to a previous file mask or branch can resolve mismatches.

Do not enable automatic push in Weblate and manual pushes from another CI system on the same branch at the same time. Choose a single source of truth to avoid merge conflicts.

Translation memory grows with each committed translation. On limited storage, periodically prune or archive the TM from Administration → Translation memory.

In case of data loss, restore the Weblate database backup and re-add the component using the same repository URL and file mask. The component will re-sync files from Git. This is a state-changing operation, so keep regular database backups.