Profiles

A profile is a named, versioned manifest of label keys for a specific locale combination. It is the unit you publish, version, diff, and roll back. Everything else in Shipeasy Translations — drafts, AI translations, the loader script, validation in CI — pivots around the profile.

If gates and configs are "one row per setting", profiles are "one snapshot per locale per publish". Every publish is immutable; revert is just "republish version N".

Naming

Profiles use locale:

The locale is BCP-47 (en, fr, pt-BR, zh-Hant). The optional :suffix (:dev, :staging, :prod) is just part of the profile name — a convention teams use to keep an in-review copy separate from the live one.

Anatomy of a profile

Every profile is a row in the project's database plus a published bundle in KV. The dashboard's Profiles list surfaces it with rough shape { id, name, locale, role, current_version, key_count, missing_count, stale_count, published_at } — see packages/core/src/db/schema.ts (labelProfiles) for the canonical fields.

The runtime fetches the strings via the i18n loader script (see The loader script below), which talks to https://api.shipeasy.ai/sdk/i18n/strings?profile=<name> with the client key. The published bundle is served from KV through the CDN with long TTL and explicitly purged on every publish.

Lifecycle

# name is positional; --locales is comma-separated (defaults to "en")
shipeasy i18n profiles create fr --locales fr

# Source profile — pushed from a code scan
shipeasy i18n push --profile en --source codemod

shipeasy i18n publish --profile fr

Source vs target

Shipeasy Translations does not hard-code English as "the" source. The first profile you create on a project is implicitly the source: it is where the codemod pushes discovered keys, and it is the basis the AI translates from.

Other profiles are targets: they hold translations of the source's keys. You can switch the source profile in Project → Shipeasy Translations → Settings, but in practice every team picks one and sticks with it.

Profile inheritance and fallback

When a key is missing from a target profile the loader falls back to the source profile :

loader requests fr label "checkout.cta"
  ↓ fr has no value
  ↓ falls back to source profile (en)
  ↓ returns "Pay"

This means an in-progress French translation never breaks the page — visitors see English for the missing strings until you publish translations. Fallbacks are also visible in the dashboard so you can target what to translate next; the Coverage column shows 1272 / 1284 (99.1%) per target profile.

The fallback only crosses locale. fr does not fall back to fr — staging is meant to be the place where bad translations are caught.

Per-locale profiles

Why not just one profile per locale? Because:

• Translators can work in fr while fr keeps serving last week's strings.
• New keys land in en:dev first; you do not need to translate them until they are promoted to staging or prod.
• An emergency copy fix in en does not require redoing translation review for development branches.
• Preview deployments (Vercel, Cloudflare Pages branch previews) can pin themselves to :dev or :staging so QA sees the unreviewed copy without it leaking to users.

Promotion (fr:staging → fr:prod) is a dashboard operation today — open Translations → Profiles → fr:staging → Promote and pick the destination. A CLI i18n promote subcommand is on the roadmap.

The recommended flow: write and translate in staging, validate (shipeasy i18n validate ./src --profile fr:staging), then promote to prod from the dashboard. Promotion creates a draft on the destination so you still get one final review before it ships.

Pinning a build to a version

Drop the loader into your page once; it reads data-key (your client SDK key) and data-profile (the locale:env profile, e.g. fr:prod) and installs window.i18n with t(key, vars):

<script
  src="https://api.shipeasy.ai/sdk/i18n/loader.js"
  data-key="sdk_client_..."
  data-profile="fr:prod"
></script>

The loader always serves the current published version. Per-page version pinning (snapshot deploys, locked landing pages) isn't a shipped feature today — the workaround for "freeze the copy for this signed contract" is to publish into a separate, no-longer-edited profile (e.g. fr:contract-2026-q2) and point that page's script tag at it.

API

The same operations are available over HTTPS for programmatic use; the CLI is a thin wrapper over these.

All endpoints take a personal access token or a CI key. The runtime SDK key cannot create or publish profiles — it is read-only against the loader URL.

Limits

Hitting a limit does not break published profiles — it blocks new publishes until you upgrade or prune. Old versions past the retention window are deleted from KV; the metadata row stays so you can see what was deleted.