What is Contextual Translation?
Contextual translation means translating a string with knowledge of where and how it appears. Short UI strings are the most context-dependent text there is: "Post" could be a verb on a button or a noun in a feed, "Save" could target a file or a discount. Many languages must commit to one reading, so a translator without context is guessing.
Context takes several concrete forms: a description attached to the key ("button label, submits the comment form"), screenshots of the string in place, the key name itself when conventions are good, character limits for constrained UI, and notes about placeholder values ("this is a person's name"). Passing the same information to machine translation and LLMs improves their output for exactly the same reason.
The cheapest context is the kind captured at authoring time. A developer adding a key knows precisely what it does; a translator reading it months later does not. Workflows that let developers attach a one-line note to each key pay for themselves in avoided rework.
Context in a Laravel lang setup
Laravel's lang files have no field for context. A key maps to a string and nothing more, so context has to live around it: in the key name, in comments, or in the tool translators work in.
Key names are the context you get for free, provided keys are structured. With natural-language JSON keys, every occurrence of the same English text is the same key, so Post the verb and Post the noun can only ever have one translation. Spanish needs Publicar for the button and Publicación for an item in a feed; German needs Veröffentlichen and Beitrag. Structured keys give each occurrence its own entry, and the key path tells the translator which one they are looking at.
Comments in PHP lang files help people who read the file, but they travel only as far as the raw file does. Anything a translator needs has to be where the translator works.
// lang/es.json: one key for both meanings
// right on the button, wrong as the heading of a feed item
{
"Post": "Publicar"
}
// lang/es/comments.php: the submit button (verb)
return [
'form' => ['submit' => 'Publicar'],
];
// lang/es/feed.php: the heading of a single item (noun)
return [
'item' => ['heading' => 'Publicación'],
];What useful context contains
Good context answers the questions a translator would otherwise guess at. What kind of element is this: a button, a heading, a tooltip, an error? Is the word a verb or a noun? What will each placeholder hold at runtime: a name, a number, a date, a product title? Is there a length limit, such as a mobile tab label or an email subject line? Who is reading, and does the product address them formally?
One line usually covers it: Button on the checkout page; charges the card. Max 20 characters. A screenshot settles most of what remains, and it is the only reliable way to show what sits next to the string.
Machine translation benefits from the same information. A short string that arrives with a note saying it is a button label, or that :name is a person, leaves the engine less to guess. LangSyncer, for example, passes the key name to its AI translation as context, so descriptive key paths pay off twice.
Context in other formats
gettext has the most explicit mechanism: msgctxt gives two entries with the same source text separate identities, and extracted comments, the lines starting with #., carry notes from developers to translators. XLIFF has note elements for the same purpose. ICU MessageFormat handles one specific kind of context inside the string itself: a select argument lets the translation vary with a person's gender or another runtime value.
#. Button on the comment form; submits the comment.
msgctxt "verb"
msgid "Post"
msgstr "Publicar"
#. Heading above a single item in the feed.
msgctxt "noun"
msgid "Post"
msgstr "Publicación"How to catch missing context
Context problems rarely show up in a spreadsheet; they show up on screen. Review translations in the running app, or at least against screenshots, and give extra attention to strings of one or two words, which carry the most ambiguity.
A quick audit is to look for identical English values stored under different keys. Each one marks a place where the same text may mean different things, and where a translator needs a note explaining which meaning applies.