---
title: "Define translation context"
description: "Version product knowledge, audience, style, locale conventions, and glossary bindings."
canonical_url: "https://docs.linguana.dev/docs/use-linguana/context"
markdown_url: "https://docs.linguana.dev/docs/use-linguana/context.md"
x_farming_labs_generated_preamble: true
agent:
  task: "Define and activate a shared immutable context profile."
  outcome: "UI and API jobs pin the chosen profile and glossary."
  prerequisites:
    - "Editor access to the project."
  files:
    - "The application locale integration and selected public API field allowlist."
  verification:
    - "Saving does not activate or publish, and existing releases survive activation."
  rollback:
    - "Keep the current release and use original source fallback."
  failureModes:
    - symptom: "A translation is missing."
      resolution: "Inspect the saved version and release; keep source text visible. Do not publish without explicit authorization."
---

# Define translation context
URL: /docs/use-linguana/context
LLM index: /llms.txt
Description: Version product knowledge, audience, style, locale conventions, and glossary bindings.

<!-- farming-labs:agent-contract:start -->
## Agent Contract

Task: Define and activate a shared immutable context profile.
Outcome: UI and API jobs pin the chosen profile and glossary.

### Prerequisites

- Editor access to the project.

### Files

- `The application locale integration and selected public API field allowlist.`

### Verification

- Saving does not activate or publish, and existing releases survive activation.

### Rollback

- Keep the current release and use original source fallback.

### Failure Modes

- A translation is missing. — Recovery: Inspect the saved version and release; keep source text visible. Do not publish without explicit authorization.
<!-- farming-labs:agent-contract:end -->

# Define translation context

Open **Context** in your project. The default profile starts empty. Fill in product knowledge, audience, tone, formality, and preferred or discouraged wording examples. Add locale-specific conventions such as German formal address.

**Save version** stores an immutable draft. Identical content reuses its existing version. **Activate saved version** selects it for new translation estimates and jobs. Activation does not translate or publish anything. Current releases keep serving their recorded wording.

## Surfaces and overrides

The compiler uses the `ui` surface. Runtime API surfaces, such as `products`, are created explicitly in **API content**. Each surface can use the project default or select another complete profile.

Within the selected profile, exact locale guidance takes precedence over base-language guidance. If `de-AT` exists, it overrides the base profile; otherwise `de` is used. A string's meaning note explains that string and does not override hard glossary rules.

Profiles follow the active glossary by default. They can instead pin a specific glossary version. Jobs record the resolved glossary and profile versions when created, so an in-flight job keeps its original guidance.

Profiles are limited to 16 KiB serialized. Meaning notes are limited to 512 Unicode code points. The complete model prompt, including repair instructions, remains bounded to 64 KiB. Context is structured guidance, not a repository dump.

## Version comparison and rollout

The editor shows active wording beside edited fields and resolves locale guidance without a model call. Save and activate the new version, then generate replacements through the normal budgeted workflow. Review and explicitly publish replacements when ready.

Changes invalidate incompatible translation-memory matches. Identical source under an unchanged profile and glossary can reuse exact validated memory without a model call or new charge.

Editors can save and activate profiles. Viewers can inspect them. Paid API-work authorization is owner-only; automatic provisional publication can be managed by owners/admins.

## API

Project-scoped endpoints are under `/api/v1/projects/:project`:

- `GET /context`: profiles, immutable versions, and surface assignments.
- `POST /context/versions`: `{ profileId?, name?, content }`.
- `POST /context/activate`: `{ profileId, versionId, expectedCurrentVersionId }`.
- `POST /surfaces`: `{ slug, profileId }`; null selects the project default.

All mutations require `Idempotency-Key`. Activation compares the expected current version and rejects a stale edit.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).