Context Analysis

How PolyCLI automatically extracts domain context before translating, improving terminology consistency at no cost.

Before the translation loop starts, polycli run calls the /api/analyze endpoint once. This call scans your source content and returns a short domain-context summary — for example, whether the product is a developer tool, a consumer app, or a legal service. That context is then included in every translation system prompt for the entire run.

Context analysis is free. It does not deduct any credits regardless of source file size.

Source selection

PolyCLI selects the source for analysis in this order:

  1. The source JSON file at <localesPath>/<sourceLanguage>.json — preferred because it contains all UI strings.
  2. If no JSON source is found and markdownPath is configured, the first .md file in the source language directory is used.
  3. If neither source is available, the step is silently skipped and translations proceed without context.

What the context contains

The analysis prompt asks the AI to identify the product domain, target audience, and any notable terminology conventions visible in the source strings. The result is a short paragraph — typically 2–4 sentences — injected into the system prompt as:

text
CONTEXT:
This is a developer-facing CLI tool for automated i18n. Strings include
technical terms like "delta", "lockfile", and "structured outputs". Prefer
precise, technical register and preserve CLI command names unchanged.

Failure handling

If the analysis call fails for any reason — network error, invalid API key, service unavailability — PolyCLI logs a warning and continues without context. Translation is never blocked by a failed analysis.

text
⚠ Context analysis failed — proceeding without context.

Interaction with tone and glossary

Context, tone, and glossary instructions all live in the same system prompt and are fully composable. Context provides the domain background, tone sets the register, and glossary enforces specific terminology. Each layer is independent — you can use any combination or none at all.