Setting Up Weblate Component Auto-Discovery for Automated Translation Projects

Desired outcome

Enable Weblate to automatically create translation components for each matching directory or file set in a version-controlled repository, using a shared component template for VCS, file format, and propagation settings.

Prerequisites

• A running Weblate instance (installed via Docker or from source) with administrative access.
• A reachable VCS repository (Git, Mercurial, or Subversion) that follows a consistent layout, e.g., each sub-project lives in its own directory under a common root.
• Optionally, a PostgreSQL database for storing component metadata (the default SQLite works for small setups but PostgreSQL is recommended for production).
• Sufficient disk space and CPU capacity to handle the initial scan of the repository.

Focused procedure

1. Log in as an administrator and navigate to Manage → Auto-addons.
2. Enable the Repository auto-addon if it is not already active.
3. Define the repository URL mask:
   • In the Repository URL mask field enter a pattern that matches the repositories you want to scan, for example:
   • https://github.com/example/<project>.git
   • The placeholder <project> will be replaced by each directory name found under the repository root.
4. Select a component template:
   • Choose an existing component (or create a new one) that has the VCS, file format, translation propagation, and other settings you want to reuse.
   • In the Component template dropdown pick that component.
5. Schedule the discovery cron job (if not using the built-in scheduler):
   • Weblate provides a management command weblate autoaddon that can be run via cron.
   • Add a cron entry such as:
   • 0 * * * * /usr/local/bin/weblate autoaddon --settings myproject.settings >> /var/log/weblate/autoaddon.log 2>&1
   • This runs the discovery hourly; adjust frequency as needed.
6. Run the discovery manually first to verify behavior:
   • Execute weblate autoaddon from the command line.
   • Watch the output or check the log file for entries like "Component auto-discovery started" and "Finished processing X repositories".
7. Review the generated components:
   • In the Weblate UI go to Manage → Projects, select your project, and open the Components tab.
   • Confirm that each expected sub-project appears as a component with the correct VCS URL (derived from the mask) and file mask.
   • Open a few components to ensure the source language file is listed and string counts are reasonable.
8. Enable translations once you are satisfied that the components are correct.

Expected checks

• UI verification: New components appear under the project, each showing the expected repository URL and file mask.
• Log verification: The Background tasks log (accessible via Manage → Background tasks) contains a recent entry for "Component auto-discovery" with a success status.
• API verification: Run a GET request to the Weblate REST API, e.g.:

GET /api/projects/<project-slug>/components/
Authorization: Token <your-api-token>
Accept: application/json

The response should list components whose vcs and repo fields match the pattern you supplied.

• Component inspection: Opening a component in the UI shows the source file, a non-zero string count, and the propagation settings inherited from the template.

Recovery options

• Disable the auto-addon: Return to Manage → Auto-addons and turn off the Repository auto-addon to stop further automatic component creation.
• Delete unwanted components: In the UI, select each erroneous component and use the Delete button, or use the API:

DELETE /api/components/<project-slug>/<component-slug>/
Authorization: Token <your-api-token>

• Revert to a database snapshot: If you took a snapshot (e.g., a pg_dump or Docker volume backup) before running discovery, restore it to return to the prior state.
• Adjust the URL mask and re-run: Edit the mask to exclude problematic paths, disable the auto-addon, remove any incorrectly created components, then re-enable the auto-addon and run discovery again.

Limitations and practical verification

Component auto-discovery can generate many components quickly; on large monorepos this may increase database size and CPU usage during the initial scan. Monitor the Background tasks log for long-running or failed jobs. Overlapping URL masks or ambiguous directory patterns may produce duplicate components, requiring manual cleanup. The feature depends on network access from the Weblate host to the VCS repository; authentication failures or intermittent connectivity will cause discovery to skip those repositories silently, so regularly check the logs for warnings.

To confirm that discovery is working as intended after a scheduled run, repeat the UI and API checks listed above. If the component list matches your expectations and the logs show a success status, the setup is functioning correctly.