Write a localization brief

Explain what readers should understand, which choices translation must preserve, and who can resolve questions about the result.

When you revise content, you make decisions that the sentence alone may not fully explain. A term names a particular product concept. A qualification keeps a claim accurate. The order of an argument helps readers understand why it matters. A localization brief gives the translator access to those decisions.

Keep the brief tied to actual source content. Its job is to explain the meaning and intended effect, not to invite the translator to invent new product facts or promises.

Begin with the reader's situation #

Describe who will encounter the text and what they need to understand or do. A locale identifies a language audience; it does not explain whether the text is a first introduction, a warning, or a response to a problem.

Keep the source passage and revision available. Add product definitions, claim evidence, or surrounding context where they change the interpretation. Identify the person who can resolve source meaning and the qualified reviewer who can judge the target wording.

Record region, script, and register when they matter. A language code alone may not settle the appropriate form of address or required wording.

Make the brief specific enough to use #

For an invitation message in ExampleApp, a brief could say:

QuestionBrief
What is being translated?An invitation message at a recorded source revision: “An administrator must approve the invitation before access is granted.”
Who reads it?A colleague waiting to join ExampleApp's shared workspace.
What should they understand?Access depends on prior administrator approval; the invitation alone does not grant access.
Which term needs context?“Workspace” names the product's shared project area, not a physical office.
What should remain intact?The approval requirement, its order relative to access, and any variables or destinations supplied by the application.
Who resolves questions?The product owner confirms access behavior; a locale-qualified reviewer judges wording; the content owner approves release.

Confirm the source claim with its owner before translating it. If the requirement is unclear or inaccurate, repair the source first.

Explain the relationship that must survive #

In the example, retaining the words for approval and access is insufficient. The translation must preserve that approval is required and comes first. A natural sentence with different structure can meet the brief; a sentence that makes approval optional cannot.

Add a counterexample when it clarifies the boundary. “An administrator may approve the invitation after access is granted” changes both obligation and order. That explains the error more precisely than asking for literal similarity to the source.

Apply the same reasoning to an action or argument. The translator can choose natural phrasing for an existing destination or supporting reason, but should not create a new action, service commitment, or piece of evidence.

Separate passage context from shared guidance #

Keep one-off facts with the passage. Put recurring terminology, instructions, and voice in the appropriate shared resource. Duplicating every requirement in all three creates copies that can drift or contradict each other.

Use correction-to-rule decisions before turning a local edit into shared guidance. Resolve conflicting requirements at their source, and keep the accepted sentence local until its broader scope is approved.

Deliver the context through a supported mechanism #

For an API caller, use the actual context and hint fields of that interface. For files, follow the relevant format handler. A retained comment becomes translator guidance only when the handler forwards it.

Follow Translate to the selected workflow, and keep the brief's source revision and configuration with the output. Then compare the target with the intended meaning, terminology, structure, and audience requirements. Render it where variables, links, or layout affect use.

If the result fails, name the exact requirement. If the brief was ambiguous, revise that definition and record the change. A finished brief lets another person explain the translation decision without relying on the original author's presence.