Translation work schema

Read this when creating a glossary, editing translation-work.jsonl outside a text editor, choosing localized route paths, or preparing approval records.

Work records

Each JSONL line represents exactly one source field:

{
  "id": "item-…",
  "sourcePath": "/about",
  "targetPath": "/es/about",
  "routeFamily": "about",
  "field": "sections.0.blocks.0",
  "sourceText": "Meet the doctor.",
  "sourceTextSha256": "…",
  "targetText": "Conozca al doctor.",
  "status": "machine-draft",
  "protectedTokens": [{ "source": "Todd C. Rau, M.D.", "target": "Todd C. Rau, M.D." }]
}

Fill only targetText and status in batches/*.jsonl. Batch records are translation-memory items: one unique source string plus the recordIds of every bound field. Keep every other field byte-identical, then run merge to expand the memory into a new field-level JSONL. merge verifies the batch, memory, and record sets; apply verifies the work manifest, record ids, field paths, source text/hash, route targets, and protected tokens.

Glossary

The optional glossary is JSON:

{
  "styleGuide": ["Use formal patient-facing usted Spanish consistently."],
  "forbiddenTargetPatterns": [
    { "id": "informal-pronouns", "pattern": "\\b(?:tú|tu|tus|te|ti|contigo)\\b", "flags": "iu" }
  ],
  "terms": [
    { "source": "Example Aesthetic Center", "target": "Example Aesthetic Center" },
    { "source": "tummy tuck", "target": "abdominoplastia", "caseSensitive": false }
  ],
  "routePaths": {
    "/about": "/es/acerca-de"
  }
}

styleGuide is optional project-owned guidance for translators and reviewers. Polytoed preserves its hash as part of the immutable glossary input but does not pretend it can mechanically certify tone, register, medical accuracy, or compliance with that guidance. When a narrow project rule is mechanically testable, forbiddenTargetPatterns makes apply and validate fail with the named rule. Keep those patterns specific enough to avoid treating ordinary target-language words as errors; human review still owns meaning and voice.

Only terms present in a source field become protected tokens for that record. A glossary target may differ from its source; the expected target form must appear in targetText.

Provider drafts

Polytoed can optionally fill translation-memory items with Google Cloud Translation Advanced v3. This is a drafting step, not approval. The local JSON glossary above remains part of the immutable run and is applied after the provider returns. A Google glossary resource is a second, provider-side copy used to influence generation; keep it synchronized from the reviewed project glossary and record the resource name with the run.

Provider output is written only to a new run. provider-provenance.json records the provider, project, location, model/glossary resource, source-manifest hash, request/response hashes, counts, and pending-review status. It does not contain the IAM token or raw request/response text. Every provider-filled record remains machine-draft, then follows the normal merge, apply, rendered review, and approval flow.

Approval

Applied routes deliberately contain:

{
  "translationStatus": "machine-draft",
  "translationReview": {
    "status": "pending",
    "sourceRecordSha256": "…"
  }
}

After a qualified human reviews the rendered page, a project-owned review step may change the route to translationStatus: "approved" and record translationReview.status: "approved", reviewedBy, reviewedAt, and the unchanged sourceRecordSha256. Polytoed validates this evidence but never creates or promotes it.