Localized Message Envelope Prompt Template

This prompt is for internationalization (i18n) engineers and API platform teams who need to serve user-facing strings inside a predictable, locale-aware API response envelope. The core job-to-be-done is not translation itself, but the selection, assembly, and wrapping of pre-existing translated content into a standard contract that clients can depend on. Use it when your API must respect the Accept-Language header, return messages keyed by locale code, and provide a transparent fallback_chain so that mobile apps, web frontends, and third-party integrators always know which locale was resolved and why. The prompt assumes you already have translated strings stored in a database, CMS, or translation management system (TMS) and that the model's role is to act as a content assembler, not a translator.

The ideal user has a set of message keys and their translations available as structured input—typically a JSON map of locale codes to message maps. The prompt enforces a strict JSON envelope structure with a messages map, a resolved_locale field, and a fallback_chain array. This shape is designed to be parsed reliably by client SDKs and API gateways without custom deserialization logic. The fallback_chain is particularly important for debugging: it tells the client that fr-CA was requested, but only fr was available, so the response fell back accordingly. This transparency prevents silent failures where a client displays the wrong language without knowing it.

Do not use this prompt when you need the model to perform translation. If your system lacks pre-translated content and you expect the model to generate translations on the fly, you need a different prompt with translation quality controls, terminology constraints, and post-generation review steps. This prompt also should not be used for single-locale applications where locale negotiation is unnecessary—a simpler response shape without the envelope overhead would be more appropriate. Finally, avoid this prompt when the message content includes dynamic variables that require interpolation before display; the envelope structure handles static strings well, but variable substitution should happen in the application layer after the envelope is received to avoid injection risks.

Before using this prompt, ensure you have a clear mapping of which locales your system supports and a defined fallback hierarchy. The model can only select from the translations you provide; it cannot invent missing locales. If your input data is incomplete, the fallback_chain will reflect that gap, and clients should be built to handle missing translations gracefully. Wire this prompt into your API gateway or backend-for-frontend layer where the Accept-Language header is available, and always validate the output against the expected JSON Schema before returning it to clients. For high-risk regulated content, add a human review step for the assembled envelope before it reaches production.

This prompt template is designed to be placed directly into your system instructions or sent as a user message. It instructs the model to produce a structured JSON response envelope containing translatable message fields keyed by locale. The envelope reflects the client's Accept-Language header, implements a fallback chain for missing translations, and ensures all output is safe for UTF-8 transport. Before using this template, ensure you have the source message in a canonical language, a list of supported locales, and the client's language preferences.

textCopy
You are a localization-aware API response generator. Your task is to produce a JSON response envelope containing a message localized into one or more target locales.

## INPUT
- Source Message: [SOURCE_MESSAGE]
- Source Language: [SOURCE_LANGUAGE]
- Supported Locales: [SUPPORTED_LOCALES]
- Client's Accept-Language Header: [ACCEPT_LANGUAGE_HEADER]

## TASK
1. Parse the `Accept-Language` header to determine the client's preferred locales in priority order.
2. Intersect the client's preferences with the `Supported Locales` list to find the best match.
3. Translate the `Source Message` from the `Source Language` into the best-matching locale. If the best match is the source language, return the source message unchanged.
4. If no direct match is found, apply a fallback chain: match on primary language subtag (e.g., `fr` matches `fr-CA`), then fall back to the first supported locale in your list.
5. Generate a JSON response envelope with the following structure.

## OUTPUT SCHEMA
{
  "status": "success" | "partial" | "unavailable",
  "requested_locale": "string (the client's top preference)",
  "resolved_locale": "string (the locale actually used for the message)",
  "message": "string (the localized message)",
  "fallback_chain": ["string (ordered list of locales attempted before resolving)"],
  "available_locales": ["string (list of all supported locales)"]
}

## CONSTRAINTS
- The `message` field must be valid UTF-8 with no unescaped control characters.
- If no supported locale can be matched, set `status` to "unavailable", `resolved_locale` to null, and `message` to an empty string.
- If a fallback was used, set `status` to "partial". Otherwise, set it to "success".
- Do not include any text outside the JSON object.

To adapt this prompt, replace the square-bracket placeholders with your application's data. [SOURCE_MESSAGE] should be the canonical text you need to localize. [SUPPORTED_LOCALES] is a JSON array of IETF BCP 47 language tags your application serves, such as ["en-US", "fr-CA", "es-MX"]. [ACCEPT_LANGUAGE_HEADER] is the raw string value from the client's HTTP request. For high-risk workflows where translation accuracy is critical, such as legal or medical disclaimers, add a [RISK_LEVEL] constraint that forces the status to "unavailable" and the message to an empty string unless a direct, non-fallback locale match is found, and always route the output for human review before serving it to the client.

The localized message envelope prompt is designed to sit behind an API gateway or backend-for-frontend (BFF) layer that already handles Accept-Language header parsing and locale negotiation. Before the prompt ever sees a request, your application should extract the user's preferred locale from the Accept-Language header, resolve it against your supported locale list using standard lookup (e.g., en-US → en → default), and inject the resolved locale and fallback chain directly into the prompt's [LOCALE] and [FALLBACK_LOCALES] placeholders. Do not pass raw Accept-Language strings to the model—the model should receive already-resolved locale decisions to avoid inconsistent negotiation logic. The [MESSAGE_KEY] and [MESSAGE_PARAMS] placeholders should come from your application's internal message catalog lookup, where [MESSAGE_KEY] is a stable identifier like order.confirmation.subject and [MESSAGE_PARAMS] is a JSON object of interpolation values such as {"order_id": "ORD-1234", "total": "$45.00"}.

Post-validation is critical because a malformed envelope can break every client that consumes your API. After the model returns its response, run a structured validation step that checks: (1) the top-level object contains the required messages key; (2) every locale key in messages matches one of the requested locales or fallback locales; (3) the resolved message for the primary locale is non-empty; (4) interpolation parameters from [MESSAGE_PARAMS] are present in the output text (verify with simple substring or regex checks on each parameter name); (5) the output is valid UTF-8 with no mojibake or encoding artifacts. If validation fails, retry once with the same prompt but append the validation error as a [PREVIOUS_ERROR] context field so the model can self-correct. If the retry also fails, fall back to your application's static message catalog for the resolved locale and log the failure for investigation. Never return a raw model failure to the client.

Observability hooks should capture: the resolved locale, the fallback chain used, the message key, the model's latency, the validation pass/fail status, and a hash of the final output envelope. Log these as structured events with a trace_id that ties the prompt call to the originating API request. For high-traffic endpoints, consider caching resolved message envelopes keyed by (message_key, locale, params_hash) with a TTL that matches your content update cadence. Model choice matters: use a fast, instruction-following model like GPT-4o-mini or Claude 3.5 Haiku for this task—localization envelopes are latency-sensitive and don't require deep reasoning. Avoid models with known encoding issues for non-Latin scripts. If your application serves more than 20 supported locales, split the prompt into batches of 10-15 locales per call to stay within output length limits and reduce the risk of truncated locale blocks. Always include a human review gate for new message keys before they go live: run the prompt against your full locale matrix, spot-check 3-5 locales manually, and only promote the envelope to production after confirming no missing translations or interpolation errors.