Implementation Guide

i18n Implementation Checklist

A comprehensive checklist for implementing internationalization in your application, based on a decade of production experience with i18n systems.

Pre-Implementation Planning

Requirements Gathering

Identify target markets and languages (initial + future roadmap)
Define source language (typically English, but not always)
Determine if you need RTL (Right-to-Left) support (Arabic, Hebrew, Persian, Urdu)
Identify locale-specific requirements beyond translation (date formats, currencies, phone numbers)
Document cultural considerations (colors, imagery, idioms that don't translate)
Define translation workflow (manual, AI-assisted, professional translators, or hybrid)
Establish translation quality requirements (machine translation acceptable vs. human review required)
Identify legal/compliance requirements (GDPR consent text, terms of service must be professionally translated)

Technical Architecture

Choose i18n library/framework appropriate for your stack
- React: next-intl, react-i18next, react-intl
- Vue: vue-i18n
- Angular: @angular/localize, ngx-translate
- Mobile: flutter_localizations, react-native-i18n
- Backend: i18next (Node.js), go-i18n (Go), gettext (Python/PHP)
Decide on translation file format (JSON, YAML, PO, XLIFF, ARB)
Plan translation file structure (single file vs. namespaced/split files)
Design key naming convention (flat vs. nested, namespacing strategy)
Determine locale detection strategy (URL path, subdomain, cookie, header, user preference)
Plan fallback strategy (missing translations, unsupported locales)
Design pluralization strategy (different rules per language)
Plan for interpolation/variable substitution in translations
Consider translation memory and glossary requirements

Infrastructure

Set up translation management system (TMS) or platform (IntlPull, Lokalise, Crowdin, Phrase)
Configure CI/CD pipeline for translation file sync
Plan for translation file versioning and rollback
Set up monitoring for missing translations in production
Configure CDN/caching strategy for translation files
Plan for OTA (Over-the-Air) translation updates if needed (mobile apps)

Implementation Phase

Code Preparation

String Extraction

Audit codebase for hardcoded strings
Extract user-facing strings to translation keys
Remove hardcoded strings from:
- UI components (buttons, labels, headings)
- Form validation messages
- Error messages and alerts
- Success/confirmation messages
- Email templates
- Push notifications
- SMS messages
- API error responses (if user-facing)
- Meta tags (title, description, og:tags)
- Alt text for images
- ARIA labels for accessibility
Keep non-translatable strings hardcoded (API endpoints, technical identifiers, code constants)

Key Naming

Establish consistent key naming convention
- Example: {namespace}.{section}.{element}.{variant}
- Example: auth.login.button.submit or errors.validation.email.invalid
Use descriptive keys that indicate context (avoid generic keys like button1, text2)
Group related keys by feature/page/component
Document key naming convention for team
Set up linting rules to enforce naming convention

Code Integration

Install and configure i18n library
Set up translation file loading mechanism
Implement locale detection and switching
Create translation hook/utility for components
Implement pluralization support
Implement interpolation/variable substitution
Add support for rich text formatting (bold, links, etc.)
Implement date/time formatting with locale awareness
Implement number formatting (decimals, thousands separators)
Implement currency formatting
Set up translation context providers (React Context, Vue provide/inject)

Translation Files

File Structure

Create translation file structure
- Single file per language: en.json, es.json, fr.json
- Or namespaced: en/common.json, en/auth.json, en/dashboard.json
Set up source language file as single source of truth
Implement translation file validation (JSON schema, type checking)
Add translation file to version control
Set up automated translation file generation from code

Content Organization

Organize translations by namespace/feature
- common - Shared strings (buttons, navigation, footer)
- auth - Authentication flows
- errors - Error messages
- validation - Form validation
- emails - Email templates
- Feature-specific namespaces
Add context comments for translators
Include examples for variables/placeholders
Document pluralization rules
Provide character limits for UI strings (button text, tooltips)

RTL Support (if applicable)

Add RTL stylesheet or CSS-in-JS support
Test layout with dir="rtl" attribute
Flip directional properties (margin-left → margin-right)
Use logical properties (margin-inline-start instead of margin-left)
Test icons and images (some need flipping, some don't)
Test form inputs and validation
Test date pickers and calendars
Verify text alignment (left/right/center)
Test scrolling behavior
Verify animations and transitions

Locale-Specific Formatting

Dates and Times

Use locale-aware date formatting library (Intl.DateTimeFormat, date-fns, dayjs)
Format dates according to locale (MM/DD/YYYY vs DD/MM/YYYY vs YYYY-MM-DD)
Format times according to locale (12-hour vs 24-hour)
Handle timezone display and conversion
Format relative times ("2 hours ago", "yesterday")
Localize calendar components
Localize date range pickers

Numbers and Currency

Use locale-aware number formatting (Intl.NumberFormat)
Format decimals (comma vs period as decimal separator)
Format thousands separators (comma, period, space, none)
Format percentages
Format currency with correct symbol and position
Handle currency conversion if needed
Display prices with correct decimal places per currency

Other Formats

Format phone numbers according to locale
Format addresses according to locale (field order, postal code format)
Format names according to locale (given name first vs family name first)
Localize units of measurement (metric vs imperial)

Translation Workflow

Initial Translation

Translate source language to target languages
Use AI translation for initial draft (if acceptable)
Review AI translations for accuracy and cultural appropriateness
Send to professional translators for review (if required)
Implement glossary for consistent terminology
Set up translation memory to reuse translations

Ongoing Translation

Set up automated detection of new/changed strings
Configure CI/CD to flag missing translations
Establish process for translating new features
Set up notification system for translators
Implement translation review/approval workflow
Version translations alongside code releases

Quality Assurance

Review translations in context (not just in spreadsheet)
Check for truncated text in UI
Verify placeholder/variable substitution works
Test pluralization rules for each language
Check for cultural appropriateness
Verify tone and formality match brand voice
Test with native speakers
Check for consistency across the application

Testing

Pseudo-Localization Testing

Implement pseudo-localization for development environment
Test with accented characters (Ȧççéñţéð Ţéẋţ) to verify encoding
Test with extended strings (150% length) to verify layout flexibility
Test with RTL simulation to catch directional issues early
Verify all UI elements handle edge cases (very long text, special characters)
Use pseudo-localization to identify hardcoded strings
Test with character doubling to simulate languages like German/Finnish

Functional Testing

Test locale switching functionality
Test locale persistence (cookie, localStorage, database)
Test fallback to default locale
Test missing translation handling
Test with very long translations (German, Finnish)
Test with very short translations (Chinese, Japanese)
Test special characters and diacritics (é, ñ, ü, ø, ß)
Test emoji and Unicode support
Test pluralization rules for each language
Test variable interpolation
Test rich text formatting (bold, links, etc.)

Visual Testing

Test UI layout with different text lengths
Test button text doesn't overflow
Test form labels and inputs
Test tooltips and popovers
Test modals and dialogs
Test navigation menus
Test tables and data grids
Test mobile responsive layouts
Test RTL layouts (if applicable)
Take screenshots of each page in each language

Browser/Device Testing

Test on Chrome, Firefox, Safari, Edge
Test on iOS Safari
Test on Android Chrome
Test on different screen sizes
Test with screen readers (accessibility)
Test keyboard navigation

Performance Testing

Measure translation file load time
Test with slow network connections
Verify translation files are cached properly
Test lazy loading of translation namespaces
Monitor bundle size impact of i18n library

SEO and Metadata

URL Structure

Choose URL structure for locales
- Path: example.com/en/about, example.com/es/about
- Subdomain: en.example.com, es.example.com
- Domain: example.com, example.es
- Query param: example.com/about?lang=es (not recommended for SEO)
Implement hreflang tags for all language versions
Set up canonical URLs
Configure sitemap with language alternates
Set up proper redirects based on Accept-Language header (optional)

Meta Tags

Translate page titles
Translate meta descriptions
Translate Open Graph tags (og:title, og:description)
Translate Twitter Card tags
Translate JSON-LD structured data
Set html lang attribute dynamically

Content

Translate all page content
Translate blog posts and articles
Translate help documentation
Translate legal pages (terms, privacy policy)
Translate marketing pages
Translate error pages (404, 500)

Accessibility

Ensure lang attribute is set correctly on html element
Set lang attribute on elements with different language content
Translate ARIA labels and descriptions
Translate alt text for images
Test with screen readers in each language
Ensure form validation messages are translated
Ensure error messages are translated and accessible

Documentation

Developer Documentation

Document i18n architecture and design decisions
Document key naming convention
Document how to add new translations
Document how to add new languages
Document translation workflow
Document locale detection and switching logic
Document fallback behavior
Create code examples for common i18n patterns
Document performance considerations

Translator Documentation

Create translator guide with context for each namespace
Document character limits for UI strings
Provide screenshots of where strings appear
Document variables and placeholders
Document pluralization rules
Provide glossary of terms
Document tone and style guidelines
Provide examples of good vs bad translations

Monitoring and Maintenance

Production Monitoring

Set up error tracking for missing translations
Monitor translation file load failures
Track locale switching events
Monitor user language preferences
Set up alerts for translation errors
Track translation coverage per language

Analytics

Track which languages users prefer
Track locale switching behavior
Monitor conversion rates per language
Track engagement metrics per language
Identify which languages need more content

Maintenance

Schedule regular translation reviews
Update translations when features change
Remove unused translation keys
Refactor translation keys when needed
Keep translation libraries up to date
Monitor for new language requests from users

Mobile-Specific Considerations

iOS Localization

Configure Info.plist with CFBundleLocalizations for supported languages
Use NSLocalizedString for all user-facing strings
Test with iOS Settings → General → Language & Region
Verify VoiceOver works correctly in all languages
Test with different text sizes (Dynamic Type)
Handle keyboard layouts per language
Test with different region formats (date, time, number)
Verify Storyboards/XIBs are localized
Test app name localization (InfoPlist.strings)

Android Localization

Create strings.xml for each locale (values-es, values-fr, etc.)
Use getString(R.string.key) for all user-facing strings
Test with Android Settings → System → Languages
Verify TalkBack works correctly in all languages
Test with different font scales (Settings → Display → Font size)
Handle input methods per language (IME)
Test with different locale configurations
Verify resource qualifiers are correct (values-es-rMX)
Test app name localization (strings.xml in values-*)

React Native / Expo

Configure app.json with supported languages
Test OTA updates for translations
Verify native modules respect current locale
Test with device language changes at runtime
Handle platform-specific overrides (iOS vs Android)
Test with Expo localization API
Verify AsyncStorage persists locale preference
Test with different device locales

Security Considerations

XSS Prevention

Sanitize user input before displaying in translations
Escape HTML in translated strings
Use safe interpolation methods (avoid dangerouslySetInnerHTML)
Validate translation file sources
Implement Content Security Policy headers
Audit third-party translation services for security

Injection Prevention

Validate locale parameter against whitelist
Prevent path traversal in locale file loading
Sanitize translation keys from user input
Validate translation file integrity (checksums)
Use parameterized queries for translated database content
Avoid eval() or Function() with translation strings

Data Privacy

Ensure GDPR compliance for all languages
Translate privacy policies accurately (professional translation)
Handle consent management per locale
Respect regional data regulations (CCPA, LGPD, etc.)
Audit translation service data handling practices
Encrypt translation files containing sensitive content

Performance Optimization

Bundle Size

Measure bundle size per language
Implement code splitting for translations
Lazy load non-critical translations
Use tree-shaking for unused keys
Compress translation files (gzip/brotli)
Consider using translation CDN

Runtime Performance

Cache parsed translations in memory
Avoid re-parsing translations on every render
Use memoization for translation functions
Batch translation updates
Profile translation lookup performance
Monitor memory usage with multiple locales loaded

Network Optimization

Implement HTTP/2 for parallel translation file loading
Use service workers for offline translation support
Set appropriate cache headers (1 year for versioned files)
Implement cache busting for translation updates
Use CDN for translation file delivery
Consider translation API for dynamic content

Common Pitfalls to Avoid

Don't concatenate translated strings (breaks grammar in many languages)
Don't assume text length will be similar across languages
Don't hardcode date/number formats
Don't use flags to represent languages (flags represent countries, not languages)
Don't translate technical terms that should remain in English (API, URL, etc.)
Don't forget to translate error messages
Don't forget to translate email templates
Don't forget to translate meta tags and SEO content
Don't use machine translation without review for legal/compliance text
Don't assume left-to-right layout
Don't forget about pluralization rules (many languages have complex rules)
Don't use gender-specific language without considering all languages
Don't forget to test with real content, not Lorem Ipsum

Launch Checklist

All target languages have complete translations
All translations have been reviewed by native speakers
All pages have been visually tested in all languages
SEO metadata is translated and configured
hreflang tags are implemented correctly
Sitemap includes all language versions
Analytics tracking is set up for all languages
Error monitoring is configured
Translation workflow is documented
Team is trained on translation process
Rollback plan is in place
Performance has been tested with all languages
Accessibility has been tested in all languages
Legal/compliance text has been professionally reviewed

Post-Launch

Monitor error logs for missing translations
Collect user feedback on translation quality
Track analytics for language usage
Schedule regular translation updates
Plan for adding new languages based on user demand
Continuously improve translation quality
Keep documentation up to date
Share learnings with team

Pro Tips:

Start early: Implement i18n from day one, even if you only support one language initially. Retrofitting i18n is much harder.
Think in keys, not strings: Train your team to think "this needs a translation key" rather than hardcoding strings.
Context is everything: Provide translators with screenshots and context. The word "bank" means different things in different contexts.
Test with real content: Lorem Ipsum doesn't reveal layout issues. Test with actual translations.
Automate everything: Use CI/CD to catch missing translations before they reach production.
Plan for growth: Design your i18n system to scale to 50+ languages, even if you start with 2.
Respect cultural differences: Colors, images, and idioms that work in one culture may not work in another.
Performance matters: Lazy load translation namespaces to keep bundle size small.
Mobile-first: Mobile users are more likely to use non-English languages. Test thoroughly on mobile.
Legal compliance: Some jurisdictions require certain content (terms, privacy policy) to be available in local languages.