An AI Localization Brief That Preserves Keys, Placeholders and Plurals

A useful localization brief separates the words a translator may change from the identifiers and behavior the application depends on. Give the agent complete messages, named arguments, quantity cases and the screen context before asking for a translation.

Consider a fictional file-upload screen. It needs to tell users how many files are ready and which file failed. A fluent translation can still break that screen if it renames an argument or changes failure into success.

The examples below use ICU4J 77.1 classic MessageFormat syntax. The JSON objects are an illustrative catalog container, not an ICU resource-file format or a library loading API. If your application uses another message library, confirm its syntax first. The ICU guide explains complete-message formatting, named arguments and plural branches; the 77.1 source reference fixes the version used here.

Define the message contract before translating

Here is the entire English source catalog for this example:

{
  "files.ready": "{count, plural, =0 {No files are ready.} =1 {# file is ready.} other {# files are ready.}}",
  "upload.failed": "Could not upload {fileName}. Try again.",
  "folder.open": "Open {folderName}"
}

The three keys identify application messages. They remain identical in every locale. The values are complete messages so that translators can change word order without coordinating several fragments.

For this exercise, filenames and folder names are user-provided labels. Translate the surrounding sentence, not those labels. Rendering and escaping those values belongs to the application's output layer; message translation does not decide whether arbitrary input is safe to render as HTML.

This small contract prevents an ambiguous request such as “make the upload strings sound natural.” It tells the agent what each sentence does and which parts are data.

Translate whole messages while retaining the contract

An illustrative Simplified Chinese counterpart is:

{
  "files.ready": "{count, plural, =0 {没有就绪的文件。} =1 {已有 # 个文件就绪。} other {已有 # 个文件就绪。}}",
  "upload.failed": "无法上传 {fileName}。请重试。",
  "folder.open": "打开 {folderName}"
}

The sentence order can change. The keys, argument names and intended action cannot change silently.

The explicit =0 and =1 cases are choices for this particular message: zero gets a distinct status, one gets an English singular sentence, and the remaining counts use other. They are not a complete plural-rule recipe for every language. Other locales and messages may need additional categories and different wording. Classic ICU plural patterns require an other branch. Ask the target-language reviewer to assess the pattern as a whole rather than copying English grammatical categories into every locale.

Review concrete mistakes, not just overall fluency

Some changes deserve a question rather than an automatic correction. For example, a short button may need a more concise translation, but removing its object can make several adjacent buttons indistinguishable. Provide the available width and neighboring labels if those constraints matter.

Supply cases a reviewer can check

These are hand-authored expected strings, not output captured from an ICU runtime:

The expectations cover meaning and argument preservation. The next implementation check should actually load the catalogs through the application's chosen formatter and render the affected screens. That catches syntax, caller argument and layout problems that a side-by-side text review cannot establish.

A complete brief you can adapt

Task: localize the attached fictional file-upload messages from English
to Simplified Chinese. Use ICU4J 77.1 classic MessageFormat syntax.
The JSON catalog is our example container; do not invent a loading API.

Context:
- files.ready is a pre-upload status, not an upload-success message.
- upload.failed appears after a failed attempt and offers retry.
- folder.open is a button that opens the named folder.

Preserve:
- Exactly the same three keys and their message meanings.
- Argument names count, fileName and folderName.
- count as a nonnegative integer; labels as unchanged caller data.
- Explicit =0, =1 and other branches for files.ready in this example.
- Complete messages rather than concatenated translated fragments.

Deliver:
1. The full target catalog, with no added or omitted keys.
2. An explanation of meaningful wording or grammatical decisions.
3. Expected displays for counts 0, 1 and 3, plus budget.csv as fileName.
4. Questions about missing screen context instead of invented context.

Checks:
- Compare key sets and argument names against the source.
- Parse and format using the actual application library when available.
- Check failure/action meaning and target-language grammar separately.
- Review long labels and layout in the affected screens.

Scope: message localization only. Do not change callers, dependencies,
rendering security, locale fallback behavior or application release settings.
If you cannot run the formatter, mark the displays as expectations.

Before accepting a translation, check the key set, the arguments, the quantity branches, the meaning and the rendered screen. Each catches a different kind of mistake. A sentence can read beautifully while still asking the application for the wrong variable.