Translation & Usage API

Translation

AI-assisted translation is available on the Business plan and above.

Translate a profile

POST /v1/translate
Authorization: Bearer i18n_at_...
Content-Type: application/json

{
  "from": "en:prod",
  "to": "fr:prod",
  "missingOnly": true,
  "chunk": "checkout"
}

Field	Required	Description
from	Yes	Source profile to translate from
to	Yes	Target profile to translate into
missingOnly	No	Only translate keys with no existing value (default: false)
chunk	No	Translate a single chunk (default: all chunks)
keys	No	Translate specific keys only (array of key names)

Translation runs asynchronously and creates a draft. Poll the draft status or use webhooks.

{
  "jobId": "job_abc123",
  "status": "queued",
  "draft": {
    "id": "draft_xyz",
    "profile": "fr:prod",
    "estimatedKeys": 142
  }
}

Get translation job status

GET /v1/translate/jobs/:jobId
Authorization: Bearer i18n_at_...

{
  "jobId": "job_abc123",
  "status": "completed",
  "translated": 139,
  "skipped": 3,
  "skippedKeys": [
    { "key": "legal.tos", "reason": "contains_html" },
    { "key": "errors.generic", "reason": "too_short" },
    { "key": "brand.name", "reason": "in_glossary" }
  ],
  "draft": {
    "id": "draft_xyz",
    "previewUrl": "https://app.i18n.shipeasy.ai/dashboard/profiles/fr:prod?draft=draft_xyz"
  },
  "completedAt": "2026-04-11T10:02:30Z"
}

Job statuses: queued → processing → completed | failed

Skip reasons:

Reason	Description
contains_html	Value contains HTML tags — manual review recommended
too_short	Value is a single character or number
in_glossary	Key matches a glossary term configured as never-translate
already_translated	Key has an existing value and missingOnly: true

---

Usage metrics

Track CDN request volume and label file delivery.

Account usage summary

GET /v1/usage
Authorization: Bearer i18n_at_...

{
  "period": "2026-04",
  "plan": "pro",
  "requests": {
    "used": 84200,
    "limit": 500000,
    "percentUsed": 16.8
  },
  "translationCredits": {
    "used": 12400,
    "limit": 50000
  }
}

Usage by profile

GET /v1/usage/profiles?period=2026-04
Authorization: Bearer i18n_at_...

{
  "period": "2026-04",
  "profiles": [
    { "profile": "en:prod", "requests": 71000 },
    { "profile": "fr:prod", "requests": 9800 },
    { "profile": "de:prod", "requests": 3400 }
  ]
}

Usage timeseries

GET /v1/usage/timeseries?period=2026-04&granularity=day
Authorization: Bearer i18n_at_...

granularity accepts hour, day, or month.

---

AI Discovery manifest

The discovery manifest is a public, unauthenticated endpoint that AI agents use to understand your ShipEasyI18n setup.

GET /v1/sites/:publicKey/manifest.json

No auth required. Returns JSON describing your account's profiles, framework, translation targets, coverage, and onboarding status.

{
  "version": 1,
  "key": "i18n_pk_abc123",
  "profiles": {
    "source": "en:prod",
    "existing": ["en:prod", "fr:prod"],
    "targets": ["fr:prod", "de:prod", "es:prod"],
    "pending": ["de:prod", "es:prod"]
  },
  "framework": "nextjs",
  "frameworkVersion": "14",
  "srcDir": "src/",
  "chunks": {
    "index":    ["nav.*", "common.*", "footer.*"],
    "checkout": ["checkout.*", "payment.*"]
  },
  "coverage": {
    "en:prod": 1.0,
    "fr:prod": 0.83,
    "de:prod": 0.0,
    "es:prod": 0.0
  },
  "glossary": ["Dashboard", "Analytics"],
  "instructions": "Checkout flow is highest priority. Preserve {{variable}} tokens.",
  "onboarding": {
    "scriptTagInstalled": true,
    "keysExist": true,
    "codemodRun": true
  }
}

Expose the manifest on your domain

Proxy the endpoint from your domain so AI agents can find it via the standard /.well-known/ path:

// next.config.mjs
async rewrites() {
  return [{
    source: '/.well-known/i18n.json',
    destination: 'https://api.i18n.shipeasy.ai/v1/sites/i18n_pk_abc123/manifest.json'
  }]
}

The manifest is cached for 60 seconds and is safe to proxy publicly.