How to implement internationalization in React components using the useTranslation hook.
The useTranslation hook provides a consistent API for handling translations, formatting dynamic content, and managing locale-sensitive data across the application.
Quick Start
API Reference
formatMessage
The formatMessage function handles all text translations and supports multiple signatures. The function now requires a translation key as the first parameter, followed by the default message.
Basic Message
Message with Data
Pluralization
The formatMessage function supports ICU Message syntax for pluralization:
If you need more complex pluralization (e.g., zero, two), you can use:
Message with Components
or
Formatting a number within a message
Translation Keys
Translation keys should follow a hierarchical naming convention:
Use dots (.) to separate hierarchy levels
Start with the feature/module name
Be descriptive and specific
Use kebab-case for individual segments
Examples:
Key Structure Recommendations:
formatNumber
The formatNumber function formats numbers according to locale:
Context Parameter
The context parameter is crucial for providing translators with additional information about where and how the text is used. Combined with descriptive translation keys, this provides comprehensive context for translators:
Context Guidelines
Use descriptive keys: Translation keys should clearly indicate the feature and usage
Be specific: Include the component name and purpose in context
Include location: Mention where in the UI this appears
Explain usage: Describe the action or state being communicated
Keep consistent: Use similar patterns across related components
Common Use Cases
Error Messages
Form Labels and Placeholders
Status Indicators
Navigation and Actions
Testing Localization
Unit Testing
Component Testing
Migration from Bare Strings
Before (❌ Don't do this)
After (✅ Do this)
Best Practices
✅ Do
Always use translation keys that follow the hierarchical naming convention
Always provide context for every formatMessage call
Use descriptive keys and context that help translators understand usage
Don't define keys in a separate variable - this could break extraction of keys from code for translation.
Don't use bare strings for user-facing text
Don't use generic keys like "title", "button", or "error"
Don't concatenate translated messages
Don't use generic context like "button" or "text"
Don't forget to wrap test components with TranslationProvider
Don't format numbers manually - use formatNumber
Current Implementation Status
Stubbed useTranslation hook with working API
Number formatting using Intl API
ESLint rules for bare string detection
Troubleshooting
Common Issues
Hook used outside provider
Solution: Ensure your component tree is wrapped with TranslationProviderMissing context parameter While not required, missing context makes translation difficult. Always provide meaningful context. The shorter the string the more important context becomes.Numbers not formatting Ensure you're using formatNumber instead of manual formatting or .toString()
Development Tools
The current implementation logs all localization calls to the console in development mode:
Related Documentation
Unit Testing - Testing strategies for localized components
Components - Building reusable localized components
Making a Feature - Including localization in feature development