Skip to content

ci: add guardrail for .pot file freshness#928

Draft
gitsofaryan wants to merge 6 commits into
SeedSigner:devfrom
gitsofaryan:add-pot-check
Draft

ci: add guardrail for .pot file freshness#928
gitsofaryan wants to merge 6 commits into
SeedSigner:devfrom
gitsofaryan:add-pot-check

Conversation

@gitsofaryan
Copy link
Copy Markdown

@gitsofaryan gitsofaryan commented Apr 24, 2026

ci: add non-blocking .pot freshness telemetry for l10n automation

Summary

This PR introduces a non-blocking CI guardrail to detect drift in localizable strings, directly addressing the "Zero-Friction" maintainer vision discussed in #893. It provides the technical foundation for automated localization syncs while ensuring that the developer workflow remains uninterrupted.

🎯 Strategic Rationale

As SeedSigner moves toward a "Zero-Friction" developer experience, the goal is to remove the burden of manual .pot management from contributors. This PR is the first step in that journey:

  1. Telemetry, Not Gatekeeping: Instead of failing the build (blocking), this job provides telemetry. It identifies when the codebase and the translation template have drifted without stopping the PR from merging.
  2. Infrastructure Readiness: The logic implemented here (timestamp-aware diffing) is the exact engine needed for the future "Auto-Sync Bot" that will handle Transifex pushes automatically.
  3. Visibility: Addresses the limitation of standard CI logs by surfacing drift alerts via GitHub Job Summaries and UI annotations.

🛠️ Technical Implementation

  • Robust Diffing: Uses git diff -I'^"POT-Creation-Date: ' --exit-code to ignore auto-generated metadata noise, preventing false positives.
  • Dependency Isolation: Installs Babel only within the localization check step to keep the main test runner lightweight.
  • Actionable Guidance: When drift is detected, the CI emits a clear warning with the exact command needed for manual synchronization, while explicitly stating that the automated pipeline can handle it on merge.

📊 Competency Evidence

Successful Detection (Non-Blocking)

When strings are modified without updating messages.pot, the CI correctly identifies the drift:

  • Build Status: ✅ GREEN (Non-blocking)
  • Annotations: ::warning title=Stale .pot file::Localizable strings have changed...
  • Job Summary: A dedicated section is added to the GitHub Actions summary page for easy maintainer review.

YAML Improvement (Recommended)

I have added a GITHUB_STEP_SUMMARY to ensure the warning is visible even without digging into logs:

      - name: Check .pot file freshness
        run: |
          python -m pip install Babel setuptools
          python setup.py extract_messages
          if ! git diff -I'^"POT-Creation-Date: ' --exit-code l10n/messages.pot; then
            echo "::warning title=Stale .pot file::Localizable strings have changed but l10n/messages.pot was not updated."
            echo "### 🌐 Localization Drift Detected" >> $GITHUB_STEP_SUMMARY
            echo "Localizable strings have changed but \`l10n/messages.pot\` was not updated." >> $GITHUB_STEP_SUMMARY
            echo "The automated pipeline will handle this on merge, but you can run \`python setup.py extract_messages\` locally to sync now." >> $GITHUB_STEP_SUMMARY
          fi

This contribution is part of the Localization Contributor Pipeline project for Summer of Bitcoin 2026.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant