Documentation

Wire Polylens into your workflow

The same scan engine, three surfaces: a CI gate that breaks the build, a Git import that pulls your repo, and an MCP server your AI agents can call.

CI gate Options GitHub Actions MCP for AI agents

The CI gate

Fail the build on a regression

POST your locale files with a project token. A failing gate returns HTTP 422, so curl -f exits non zero and breaks the build like any failing test.

Create a project token

In your project under the CI tab, generate a token. It starts with plk_. Store it as a secret named POLYLENS_TOKEN.

Call the gate

One curl call per pipeline run, after your checkout step.

Read the verdict

passed plus the exact reasons. Exit code does the rest.

curl -sf https://polylens.sh/api/ci/scan \
  -H "Authorization: Bearer $POLYLENS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "failOn": "error",
        "noRegression": true,
        "files": {
          "en": '"$(jq -c . locales/en.json)"',
          "de": '"$(jq -c . locales/de.json)"'
        }
      }'

Response

{
  "passed": false,
  "reasons": ["3 error-level issue(s)", "score dropped from 82 to 71"],
  "scan": {
    "score": 71,
    "band": "drifting",
    "previousScore": 82,
    "summary": { "bySeverity": { "error": 3, "warning": 5, "info": 0 } },
    "locales": [{ "code": "de", "score": 94, "issues": 2 }]
  }
}

Options

Tune the gate

failOn"error" (default), "warning", or "none". Which severity fails the gate.

minScoreNumber 0 to 100. Fail if the health score drops below this.

noRegressionBoolean. Fail if the score is lower than the previous scan.

filesMap of locale code to JSON string. Must include the source locale.

These are the JSON body fields for raw curl calls. The polylens-ci.mjs helper exposes the same options as env vars: FAIL_ON, MIN_SCORE, and NO_REGRESSION (the helper defaults NO_REGRESSION to true).

GitHub Actions

Drop it into a workflow

Runs on every pull request. A slipped language shows up as a red check.

name: i18n health
on: [pull_request]
jobs:
  polylens:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Polylens gate
        run: |
          curl -sf https://polylens.sh/api/ci/scan \
            -H "Authorization: Bearer ${{ secrets.POLYLENS_TOKEN }}" \
            -H "Content-Type: application/json" \
            -d "{\"failOn\":\"error\",\"noRegression\":true,\"files\":{
                  \"en\": $(jq -c . locales/en.json),
                  \"de\": $(jq -c . locales/de.json)
                }}"

MCP for AI agents

Let an agent watch and fix the drift

Connect Polylens to Claude, Cursor, Perplexity, or any MCP client. The agent can score locale files, list your projects, and pull-and-rescan a connected repo. OAuth, no API key to copy. Requires the Team plan.

MCP endpoint

https://polylens.sh/api/mcp

Settings → Connectors → Add custom connector. Paste the URL below, click Connect, and sign in to Polylens when the browser opens. Same for Claude Desktop.

The connection uses OAuth 2.1 (sign in with your Polylens account). The MCP tools require the Team plan. Tools: scan_locales, list_projects, project_health, rescan_project.

Questions the docs do not answer?

Check the FAQ on the landing page