ci(i18n): install dev/test gems and use bundler-cache; add bin/i18n helper and docs; run workflow via helper

Author: rsmithlal

.github/workflows/i18n-health.yml

@@ -13,6 +13,10 @@ on:
 jobs:
   i18n-health:
     runs-on: ubuntu-latest
+    env:
+      # Ensure dev/test gems (incl. i18n-tasks) are installed
+      BUNDLE_WITHOUT: ""
+      BUNDLE_WITH: "development:test"
     if: github.event_name == 'push' || github.event_name == 'pull_request'
     steps:
       - name: Checkout code
@@ -21,23 +25,14 @@ jobs:
         uses: ruby/setup-ruby@v1
         with:
           ruby-version: '3.4.4'
-      - name: Install dependencies
-        run: |
-          gem install bundler
-          bundle install
+          bundler-cache: true
       - name: Normalize locale files
-        run: |
-          bundle exec i18n-tasks normalize
-      - name: Check missing translations
-        run: |
-          bundle exec i18n-tasks check-missing
-      - name: Check consistent interpolations
-        run: |
-          bundle exec i18n-tasks check-consistent-interpolations
+        run: bin/i18n normalize
+      - name: Run i18n checks
+        run: bin/i18n check
       - name: Upload i18n health report
         if: always()
-        run: |
-          bundle exec i18n-tasks health > i18n-health.txt
+        run: bin/i18n health > i18n-health.txt
         continue-on-error: true
       - name: Archive i18n health report
         uses: actions/upload-artifact@v4

AGENTS.md

@@ -23,6 +23,7 @@ Instructions for GitHub Copilot and other automated contributors working in this
 - **Lint:** `bundle exec rubocop`
 - **Security:** `bundle exec brakeman --quiet --no-pager` and `bundle exec bundler-audit --update`
 - **Style:** `bin/codex_style_guard`
+- **I18n:** `bin/i18n [normalize|check|health|all]` (runs normalize + missing + interpolation checks by default)
 
 ## Security Requirements
 ## Security Requirements
@@ -105,6 +106,9 @@ i18n-tasks add-missing
 i18n-tasks health
 ```
 
+## CI Note
+- The i18n GitHub Action installs dev/test gem groups to make `i18n-tasks` available. Locally, you can mirror CI with `bin/i18n`, which sets `BUNDLE_WITH=development:test` automatically.
+
 See `.github/instructions/i18n-mobility.instructions.md` for additional translation rules.
 
 # Testing Requirements

bin/i18n

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Ensure i18n-tasks (in development/test groups) is available
+export DISABLE_SPRING=1
+export BUNDLE_WITH="${BUNDLE_WITH:-development:test}"
+export BUNDLE_WITHOUT="${BUNDLE_WITHOUT:-}"
+
+usage() {
+  echo "Usage: bin/i18n [normalize|check|health|all]" >&2
+}
+
+cmd="${1:-all}"
+
+case "$cmd" in
+  normalize)
+    bundle exec i18n-tasks normalize
+    ;;
+  check)
+    bundle exec i18n-tasks check-missing
+    bundle exec i18n-tasks check-consistent-interpolations
+    ;;
+  health)
+    bundle exec i18n-tasks health
+    ;;
+  all)
+    bundle exec i18n-tasks normalize
+    bundle exec i18n-tasks check-missing
+    bundle exec i18n-tasks check-consistent-interpolations
+    ;;
+  *)
+    usage
+    exit 1
+    ;;
+esac
+