Configure Weblate Quality Checks and Auto-Fixes for Consistent Translations

Problem and Takeaway

Translation teams waste hours reviewing the same preventable errors: missing trailing punctuation, mismatched placeholders, strings that exceed UI length limits. Weblate ships with over 40 built-in quality checks and deterministic auto-fixes that run on every save and can be applied retroactively. This guide shows how to enable the right checks per component, set severity so they block or warn, activate auto-fixes that commit clean corrections, and verify the setup without rewriting shared Git history.

Prerequisites

• Weblate 5.x (per-language overrides require 5.0+).
• Admin access to the Weblate instance (Django admin UI or WEBLATE_CHECKS/WEBLATE_AUTOFIXES settings).
• A translation component already connected to a VCS repository (Git, GitHub, GitLab, etc.).
• The Weblate bot user (or SSH key/token) has write permission to the target branch so auto-fix commits can be pushed.
• Branch protection rules or a dedicated Weblate branch + merge-request workflow to prevent uncontrolled pushes to main.

Enable and Tune Checks per Component

Via the Admin UI (Recommended)

1. Open the Django admin: /admin/translation/component/.
2. Select the component → Quality checks tab.
3. For each check (e.g., TrailingPunctuationCheck, MaxLengthCheck, PythonBraceFormatCheck), choose:
   • Enabled – runs on every save.
   • Severity – Error blocks save; Warning shows a flag but allows save.
4. Save. Changes take effect immediately; no container restart needed.

Via Settings (Global Baseline)

In settings.py or docker-compose.override.yml set WEBLATE_CHECKS and WEBLATE_AUTOFIXES to lists of check/fix class paths. This affects all components; use only for checks you want everywhere (e.g., weblate.checks.same.SameCheck). Per-component UI toggles override the global list.

Concrete Example: Enforce Trailing Period and Max Length

# In component Quality checks UI
TrailingPunctuationCheck: Enabled, Severity = Error
MaxLengthCheck: Enabled, Severity = Error
# Auto-fixes
TrailingWhitespaceFixer: Enabled
EllipsisNormalizationFixer: Enabled

Now a translator who saves "Hello world" (missing period) gets a blocking error. Saving "Hello world." (double space) triggers TrailingWhitespaceFixer; Weblate commits the corrected string as a separate commit by "Weblate Bot".

Per-Language Overrides (Weblate 5.x)

Some languages legitimately omit trailing periods (e.g., Japanese). In the component view, go to Languages → pick a language → Quality checks. Disable or downgrade specific checks for that language only. This avoids global exceptions that weaken enforcement elsewhere.

Suppress Checks for Individual Strings

When a single string must violate a rule (e.g., a placeholder-heavy message that trips PlaceholdersCheck), edit the unit in the Weblate UI, open Flags, and add skip-placeholders (or the check's short name). The flag is stored in the unit's check_flags field and respected on subsequent saves.

Apply Checks Retroactively to Existing Translations

New checks don't automatically scan existing units. Run the management commands from the Weblate container shell (or via docker compose exec weblate):

1. Dry-run: weblate checkgit <project/component> – lists failing checks without changing files. Exit code 0 means clean.
2. Commit auto-fixes: weblate cleanup_translations <project/component> --fix – writes corrected strings and creates one commit per fix (or batches them). Do not use --force on shared branches; it rewrites history.

Risk: cleanup_translations --fix rewrites translation files in-place. Ensure the working tree is clean (git status shows nothing) and you have a recent backup or can run git reset --hard HEAD if something goes wrong.

Verification Steps

1. UI test: In the translation editor, create a test translation that violates an enabled error check (e.g., omit the trailing period). Save – the UI must block and show the check name.
2. Auto-fix test: Save a string with a fixable issue (double spaces). Check Repository → Commits for a new commit by "Weblate Bot" with message "Automatic fixup".
3. CLI audit: Run weblate checkgit <project/component> again; expect zero unexpected failures.
4. API integration: GET /api/components/<project>/<component>/checks/ returns failing_checks counts. Compare with the dashboard numbers.
5. Custom check unit test (if you added any): In your Django app, instantiate the check class and call check(target, source, unit) asserting True/False as expected.

Recovery Options

• Bad auto-fix commit pushed: On the protected branch, revert the bot's commit via the VCS UI or git revert <sha>. Because auto-fixes are separate commits, reverting is surgical.
• Mass corruption from cleanup_translations --fix: git reset --hard HEAD@{1} (or the last known good SHA) on the server, then force-push the corrected branch if branch protection allows. This is why a clean working tree and backup are mandatory before running the command.
• Check too noisy: Downgrade severity to Warning in the component UI, or add skip-<check> flags to specific units. Avoid disabling globally unless the check is fundamentally incompatible with your file format.

Limitations and Cautions

• Auto-fixes only run for deterministic transformations (whitespace, ellipsis, plural forms). They will not rewrite ambiguous grammar.
• MaxLengthCheck requires the source unit to have a max_length attribute (set via maxlength in XLIFF, maxlen in Android XML, or manually in the Weblate UI per unit). Without it, the check silently passes.
• Custom checks and auto-fixes execute in the Celery worker. Poorly written code can stall the queue. Always test in staging with weblate checkgit before enabling in production.
• Disabling a check globally via WEBLATE_CHECKS removal affects every component. Prefer per-component toggles.

Diagram Labels

1. Component Quality Checks UI – severity toggles per check
2. Auto-fix Commit in Repository – Weblate Bot commit example
3. CLI checkgit Output – dry-run failure list
4. REST API Checks Endpoint – failing_checks JSON payload