Prompt
How do I give translators context for UI strings
Latest observation
The best way is to give translators context, not just strings. UI text is often ambiguous out of context, so even short notes can dramatically improve translation quality.
Good ways to provide context
1. Add developer notes to each string
Include a short description of:
- Where it appears in the UI
- What it means
- What it should sound like (tone/formality)
- Any constraints like character limits
Example:
{
"save_button": {
"text": "Save",
"description": "Button in the profile editor. Saves the user's changes."
}
}
For a word like “Save,” the translator needs to know whether it means:
- “Store changes” vs.
- “Keep for later” vs.
- “Rescue”
2. Include screenshots or mockups
A screenshot is often the most useful context. It shows:
- the surrounding UI
- nearby labels
- whether the string is a button, tooltip, title, or error message
If you use a translation platform, attach screenshots to each string or screen.
3. Use translation keys that are descriptive
Keys help translators and developers understand intent.
Bad:
"btn1": "Open"
Better:
"open_settings_button": "Open"
The key itself is not a replacement for context, but it helps.
4. Group strings by feature or screen
Instead of sending translators a flat list of isolated phrases, organize them by:
- screen
- dialog
- workflow
- feature area
This helps them infer meaning from neighboring strings.
5. Provide examples
If a string can be used in multiple ways, give example sentences or usage notes.
Example:
{
"archive": {
"text": "Archive",
"description": "Verb. Button that moves the email/message out of the inbox."
}
}
6. Mark placeholders and variables clearly
Tell translators what placeholders represent.
Example:
{
"items_selected": {
"text": "{count} items selected",
"description": "Shown above a list when the user selects items. {count} is a number."
}
}
Also mention whether placeholders can be reordered in the target language.
7. Provide tone and style guidance
Tell translators whether the product should sound:
- formal or casual
- friendly or professional
- concise or explanatory
- gender-neutral, if relevant
Example:
- “Use a friendly, concise tone.”
- “Use formal address.”
- “Avoid slang.”
8. Flag ambiguous terms
Some words are especially tricky:
- “Close” could mean shut, near, or end
- “Post” could mean publish or mail
- “Reset” could mean restore defaults or clear values
Whenever possible, add a note to disambiguate.
A simple template you can use
For each string, provide:
- Key
- Source text
- Description/context
- Where it appears
- Screenshot or mockup
- Constraints (length, placeholders, tone)
Example:
{
"delete_account_warning": {
"text": "Delete account",
"description": "Dangerous action button in account settings. Permanently removes the user's account.",
"tone": "concise, serious",
"constraints": "Should be short enough for a button."
}
}
Best practices
- Don’t translate strings in isolation
- Avoid overly clever UI copy if it can be ambiguous
- Keep glossary terms consistent across the product
- Review translations in context before release
If you want the most practical workflow
Use a localization system that supports:
- string descriptions
- screenshots
- glossary/term base
- reviewer comments
- plural rules and placeholders
If you want, I can also give you:
- a JSON schema for localization context,
- a translation handoff checklist, or
- examples for i18n frameworks like i18next, ICU, or gettext.