Enhanced Message Context

Enhanced Message Context

When implementing Lingui i18n, add translator comments to messages so translators have context to provide the best translation. Even when the message text is self-explanatory, it is important to know where and how it appears in the UI to choose the correct tone, length, and wording.

When to Add Comments

Add a comment field when the message:

• Is ambiguous: Short words/phrases that can be different parts of speech
  • "Back" (noun or verb?), "Delete" (button or confirmation?), "Close" (verb or adjective?)
• Lacks UI context: Labels isolated from their surroundings
  • Table column headers, tooltip content, standalone button labels, menu items
• Has domain-specific meaning: Terms with different meanings across contexts
  • "Post" (verb or noun?), "Tag" (noun or verb?), "Follow" (social media or instruction?)
• Depends on grammatical gender: The translation depends on what the message refers to
  • "Selected" (masculine/feminine/neutral depends on what is selected)
• Uses unclear variables: Placeholder names don't reveal what they contain
  • {count} (count of what?), {name} (user name, file name, project name?)
• Could benefit from UI context even if clear: Where the text appears (button, dialog, banner, form field) affects tone and length - add a brief location or purpose comment when it helps.

Writing Effective Comments

A good translator comment includes:

1. Location: Where in the UI the message appears

   • "Button in the top navigation bar"
   • "Tooltip for the save icon"
   • "Column header in the users table"

2. Action/Purpose: What happens or what it means

   • "Navigates back to the previous page"
   • "Deletes the selected item permanently"
   • "Shows the number of unread notifications"

3. Disambiguation: Clarify part of speech or meaning

   • "Used as a verb, not a noun"
   • "Refers to email addresses, not postal addresses"
   • "Singular form, user will see 'item' or 'items' based on count"

API Reference