CLI tool to detect i18n layout issues - CSS overflows, RTL breaks, and text expansion problems. Powered by Lingo.dev
npm install lingo-guardian> The Automated DevSecOps Firewall for Internationalization
Detect UI overflows, RTL layout breaks, and missing i18n keys before they reach production.
Powered by Lingo.dev.
---
If you are an agent trying to use this tool, here is the context you need:
1. Purpose: Audits a URL for visual regressions caused by text expansion (German) or layout shifts (Arabic/RTL).
2. Core Mechanic: It uses Lingo.dev to ANY-to-ANY translate your app's source content, then uses a headless browser to detect scrollWidth > offsetWidth (Red Glow).
3. Auto-Detection: If i18n.json exists, it automatically detects and tests ALL configured locales.
---
``bashInstall globally (Optional)
npm install -g lingo-guardian
---
π Quick Start
$3
If you have an i18n.json file, the tool becomes "Zero-Config".Initialize Lingo.dev (if not done):
`bash
npx lingo.dev@latest init
`
This creates i18n.json determining your source and target languages.$3
`bash
1. Start your app server
npm run dev2. Run the audit (Auto-detects locales from i18n.json)
npx lingo-guardian lint http://localhost:3000
`---
π§ Behavior & Edge Cases
$3
If i18n.json is present in your project root:
- The tool READS config.locale.targets (e.g., ['de', 'ar', 'ja']).
- It GENERATES missing translations using npx lingo.dev run.
- It AUDITS en, de, ar, and ja automatically.$3
If i18n.json is MISSING:
- The tool logs a warning: β No Lingo.dev config (i18n.json) found.
- It falls back to Algorithmic Mode: Tests en and pseudo (algorithmic text expansion).
- It will SKIP the lingo.dev run generation step.$3
You can force specific locales regardless of config:
`bash
Ignore config and only test German and Arabic
npx lingo-guardian lint http://localhost:3000 --locale de ar
`---
π₯οΈ Live Dashboard (The "Wow" View)
Simulate user testing across multiple locales simultaneously with the Lingo-Guardian Dashboard.
`bash
npx lingo-guardian dashboard http://localhost:3000
`
(Default port: 3005)This launches a local server displaying your app in 4 parallel iframes:
1. πΊπΈ English (Source)
2. π©πͺ Pseudo (Expansion Testing)
3. π¦πͺ Arabic (RTL Layout Testing)
4. π―π΅ Japanese (Vertical/Font Testing)
Real-Time Sync: If you use the
@lingo-guardian/reporter hook in your app, any overflow detected in these panes will trigger a visual "Red Alert" on the dashboard.πͺ Developer Experience: The Reporter Hook
Install the companion hook to see issues as you code:
`bash
npm install @lingo-guardian/reporter
`Add it to your app (see Reporter Docs):
`tsx
useLingoGuardian({ enable: process.env.NODE_ENV === 'development' });
`features:
- Red Glow: Overflows get outlined in red instantly.
- VS Code Links: Clickable links in console to jump to source.
- Zero Config: Works out of the box.
---
π Source Location Detection (v0.1.11+)
The CLI now shows component names and line numbers in the audit output. This works with any frontend framework:
| Framework | Detection Method |
|-----------|------------------|
| React (CRA/Vite) |
_debugSource from React Fiber |
| Angular | ng-reflect-, _ngcontent-, custom tag names |
| Vue | data-v-* scoped style attributes |
| Any Framework | data-source, data-testid, id attributes |$3
Add
data-source attributes to your components for 100% reliable detection:`tsx
data-source="src/components/Card.tsx:42"
data-component="Card"
>
{/ content /}
CLI Output:
`
β Source β
βββββββββββββββββββ€
β Card:42 β
`---
π€ Visual PR Guardian (GitHub Action)
Turn every Pull Request into an automated visual audit. This action runs the audit and posts a Visual Report directly to the PR comments.
$3
Create
.github/workflows/lingo-guardian.yml:`yaml
name: π‘οΈ Lingo-Guardianon: [pull_request]
jobs:
visual-audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
# 1. Start your app
- name: Install & Start App
run: |
npm ci
npm run build
npm run start &
npx wait-on http://localhost:3000
# 2. Run Lingo-Guardian Action
- name: πΈ Run Visual Audit
uses: ashpreetsinghanand/lingo-guardian/packages/action@main
with:
url: 'http://localhost:3000'
lingo-api-key: ${{ secrets.LINGODOTDEV_API_KEY }}
github-token: ${{ secrets.GITHUB_TOKEN }}
# Optional:
# fail-on-error: 'true'
# locales: 'en,pseudo,ar,de' (Auto-detects if omitted)
`Inputs:
-
url (Required): The local URL where your app is running (e.g., http://localhost:3000).
- lingo-api-key (Required): Your Lingo.dev API key for generating translations.
- github-token (Required): secrets.GITHUB_TOKEN to post comments on the PR.
- fail-on-error (Optional): Set to 'true' to fail the build if issues are found.---
π§ CLI Reference
`bash
lingo-guardian lint [options]Options:
-p, --project Path to project root containing i18n.json (default: cwd)
--no-use-lingo Disable Lingo.dev auto-generation (use existing files only)
-l, --locale Explicit locales to test (Overwrites auto-detection)
-f, --format Output: table, json, html, markdown (default: table)
-s, --screenshot Save screenshots of errors to ./screenshots
--fail-on-error Exit with code 1 if issues found (CI/CD mode)
`---
π οΈ Troubleshooting
$3
Cause: Your i18n.json has buckets: {} or invalid types.
Fix: Ensure your bucket key is a valid parser (e.g., json, react).
`json
// CORRECT
"buckets": {
"json": { "include": ["locales/[locale].json"] }
}
`$3
Cause: CI/CD environment missing browser binaries.
Fix: Run npx playwright install chromium before the audit.$3
Cause: Missing API Key.
Fix:
`bash
export LINGODOTDEV_API_KEY=your_key_here
``---
MIT Β© Lingo-Guardian Team