Deployment Guide

i18n Deployment Checklist

A battle-tested checklist for deploying internationalized applications to production, covering everything from pre-deployment validation to post-deployment monitoring.

Pre-Deployment Validation

Translation Completeness

Run translation coverage report for all target languages
Verify all critical user flows have 100% translation coverage
Identify and document any intentionally untranslated content
Verify fallback translations are in place for incomplete languages
Check for empty translation values (should use fallback or source language)
Verify all new features added since last deployment are translated
Run automated tests to detect missing translation keys

Translation Quality

Review translations with native speakers for each language
Verify brand terminology is consistent (check against glossary)
Check for placeholder/variable substitution errors
Verify pluralization rules work correctly for each language
Test gender-specific translations (if applicable)
Review translations in context (not just in spreadsheet)
Check for cultural appropriateness
Verify tone and formality match brand voice

File Validation

Validate all translation files are valid JSON/YAML/format
Check for syntax errors in translation files
Verify file encoding is UTF-8
Check for BOM (Byte Order Mark) issues
Verify no duplicate keys exist
Check for trailing commas (if JSON)
Verify special characters are properly escaped
Run linter on translation files
Verify translation files are not corrupted

Code Validation

Run TypeScript/type checking on translation keys
Verify all translation keys used in code exist in translation files
Check for hardcoded strings that should be translated
Verify locale detection logic works correctly
Test locale switching functionality
Verify locale persistence (cookie/localStorage/database)
Test fallback locale behavior
Run unit tests for i18n utilities
Run integration tests for locale switching

Build and Bundle

Build Process

Build application with all languages included
Verify translation files are included in build output
Check bundle size for each language
Verify code splitting for translation files (if applicable)
Test lazy loading of translation namespaces
Verify source maps include translation files (for debugging)
Check for build warnings related to i18n
Verify environment-specific translations (staging vs production)

Bundle Optimization

Minimize translation file size (remove comments, whitespace)
Enable compression for translation files (gzip/brotli)
Verify CDN caching headers for translation files
Set up cache busting for translation files (versioning)
Consider splitting large translation files into chunks
Verify tree-shaking removes unused translations (if supported)
Test bundle size impact of adding new languages

Asset Preparation

Prepare locale-specific images (if any)
Prepare locale-specific videos (if any)
Prepare locale-specific PDFs/documents
Verify all assets are uploaded to CDN
Test asset loading from CDN
Verify asset URLs are correct for each locale

Infrastructure Setup

DNS and Routing

Configure DNS for locale-specific URLs
- Path-based: example.com/en/*, example.com/es/*
- Subdomain: en.example.com, es.example.com
- Domain: example.com, example.es
Set up SSL certificates for all domains/subdomains
Configure CDN for all locale URLs
Set up redirects for legacy URLs
Configure default locale redirect (e.g., / → /en)
Test locale detection from Accept-Language header (if implemented)

Server Configuration

Configure server to serve correct locale based on URL
Set up proper HTTP headers (Content-Language, Vary: Accept-Language)
Configure caching headers for translation files
Set up compression for translation files
Configure CORS if translations are served from different domain
Set up rate limiting for translation API (if applicable)
Configure server-side rendering for all locales (if SSR)

Database

Verify database supports UTF-8 encoding (utf8mb4 for MySQL)
Check database collation settings
Verify user locale preferences are stored correctly
Test database queries with non-ASCII characters
Set up database indexes for locale-specific queries
Verify database backups include all locale data

CDN Configuration

Upload translation files to CDN
Configure CDN caching rules for translation files
Set up cache invalidation for translation updates
Configure CDN to serve correct Content-Type headers
Test CDN performance from different geographic regions
Set up CDN failover to origin server
Configure CDN to respect Vary headers

SEO Configuration

URL Structure

Verify URL structure is consistent across all locales
Test canonical URLs for each locale
Verify hreflang tags are implemented correctly
Test x-default hreflang for language selector page
Verify no duplicate content issues between locales
Test URL redirects for locale switching
Verify URL structure matches sitemap

Meta Tags

Verify html lang attribute is set correctly for each locale
Test page titles are translated
Test meta descriptions are translated
Verify Open Graph tags are translated (og:title, og:description, og:locale)
Test Twitter Card tags are translated
Verify JSON-LD structured data is translated
Test meta robots tags (noindex for duplicate content if needed)

Sitemap

Generate sitemap with all locale URLs
Include hreflang annotations in sitemap
Submit sitemap to Google Search Console
Submit sitemap to Bing Webmaster Tools
Verify sitemap is accessible and valid
Set up automatic sitemap generation on content updates
Test sitemap with sitemap validators

Search Console

Set up Google Search Console for each locale domain/subdomain
Verify ownership for all locale properties
Submit sitemaps for each locale
Configure international targeting (if using subdomains/domains)
Monitor for hreflang errors
Set up alerts for crawl errors

Testing in Staging

Functional Testing

Test locale detection and switching
Test locale persistence across sessions
Test all user flows in all languages
Test form validation messages in all languages
Test error messages in all languages
Test success messages in all languages
Test email templates in all languages
Test push notifications in all languages (if applicable)
Test SMS messages in all languages (if applicable)

Visual Testing

Take screenshots of all pages in all languages
Compare screenshots to design mockups
Test with very long translations (German, Finnish)
Test with very short translations (Chinese, Japanese)
Test button text doesn't overflow
Test form labels and inputs
Test navigation menus
Test modals and dialogs
Test tooltips and popovers
Test tables and data grids

RTL Testing (if applicable)

Test all pages with RTL languages (Arabic, Hebrew)
Verify layout flips correctly
Test form inputs and validation
Test date pickers and calendars
Test icons and images
Test scrolling behavior
Test animations and transitions
Test text alignment

Browser/Device Testing

Test on Chrome (Windows, Mac, Linux)
Test on Firefox (Windows, Mac, Linux)
Test on Safari (Mac, iOS)
Test on Edge (Windows)
Test on iOS Safari (iPhone, iPad)
Test on Android Chrome (phone, tablet)
Test on different screen sizes (mobile, tablet, desktop)
Test with screen readers (NVDA, JAWS, VoiceOver)
Test keyboard navigation

Performance Testing

Measure page load time for each locale
Test translation file load time
Test with slow network (3G, throttled)
Verify translation files are cached
Test lazy loading of translation namespaces
Measure Time to Interactive (TTI) for each locale
Test Core Web Vitals (LCP, FID, CLS) for each locale
Profile JavaScript execution time for i18n code

API Testing

Test API responses in all languages (if API returns translated content)
Test API error messages in all languages
Verify Accept-Language header is respected
Test API with different locale formats (en-US vs en_US vs en)
Test API rate limiting per locale
Test API caching per locale

Security

Input Validation

Test for XSS vulnerabilities in translated content
Verify user input is sanitized before translation
Test for SQL injection with non-ASCII characters
Verify translation keys cannot be manipulated by users
Test for path traversal vulnerabilities in locale switching
Verify locale parameter validation (whitelist allowed locales)

Content Security

Verify Content-Security-Policy headers work with all locales
Test for mixed content warnings (HTTP/HTTPS)
Verify translation files are served over HTTPS
Test for clickjacking vulnerabilities in locale switcher
Verify no sensitive data is exposed in translation files

Access Control

Verify locale switching doesn't bypass authentication
Test that user permissions are respected in all locales
Verify locale-specific content restrictions (if any)
Test that admin interfaces are properly translated and secured

Deployment Process

Pre-Deployment

Create deployment checklist for team
Schedule deployment during low-traffic period
Notify team of deployment window
Prepare rollback plan
Back up current translation files
Back up database
Tag release in version control
Document changes in changelog

Deployment Steps

Deploy backend changes (if any)
Deploy translation files to CDN
Deploy frontend application
Verify deployment succeeded
Clear CDN cache for translation files
Clear application cache
Restart application servers (if needed)
Verify all services are running

Smoke Testing

Test homepage in all languages
Test locale switching
Test critical user flows (login, signup, checkout)
Test API endpoints
Check error logs for issues
Verify analytics tracking works
Test email sending in all languages
Verify no 404 errors for locale URLs

Post-Deployment Monitoring

Immediate Monitoring (First Hour)

Monitor error logs for missing translations
Monitor error logs for i18n-related errors
Check application performance metrics
Monitor CDN cache hit rate for translation files
Check user reports/support tickets
Monitor social media for user feedback
Verify analytics tracking is working
Check for any 404 errors on locale URLs

Short-Term Monitoring (First 24 Hours)

Monitor translation coverage metrics
Track locale switching events
Monitor user language preferences
Check conversion rates per language
Monitor page load times per locale
Track API error rates per locale
Monitor CDN performance
Review user feedback and support tickets

Long-Term Monitoring (First Week)

Analyze user engagement per language
Review translation quality feedback
Monitor SEO rankings for locale pages
Track organic traffic per language
Analyze conversion funnels per language
Review heatmaps/session recordings per locale
Monitor for translation-related bugs
Collect feedback from native speakers

Analytics Setup

Set up custom events for locale switching
Track user language preferences
Set up conversion goals per language
Create dashboards for locale metrics
Set up alerts for anomalies per locale
Track bounce rates per language
Monitor time on site per language
Track user flows per language

Error Monitoring

Set up error tracking for missing translations
Monitor for i18n-related JavaScript errors
Track translation file load failures
Monitor for locale detection failures
Set up alerts for critical i18n errors
Track error rates per locale
Monitor for encoding issues

SEO Monitoring

Search Console

Monitor for hreflang errors
Check for duplicate content issues
Monitor crawl errors per locale
Track impressions and clicks per locale
Monitor for manual actions
Check mobile usability per locale
Monitor Core Web Vitals per locale

Rankings

Track keyword rankings per locale
Monitor organic traffic per language
Track backlinks per locale
Monitor domain authority per locale (if using separate domains)
Track featured snippets per locale
Monitor local pack rankings (if applicable)

Indexing

Verify all locale pages are indexed
Check for indexation issues
Monitor index coverage per locale
Verify canonical tags are respected
Check for soft 404 errors
Monitor for duplicate content issues

Rollback Plan

Rollback Triggers

Define criteria for rollback (error rate threshold, user complaints, etc.)
Assign rollback decision authority
Document rollback process
Test rollback process in staging

Rollback Steps

Revert to previous application version
Restore previous translation files from backup
Clear CDN cache
Clear application cache
Verify rollback succeeded
Notify team of rollback
Document reason for rollback
Plan fix and re-deployment

Continuous Improvement

Translation Updates

Set up process for updating translations post-launch
Configure CI/CD for translation updates
Test translation updates in staging before production
Document translation update process
Set up notifications for translators when new keys are added

Performance Optimization

Monitor and optimize translation file size
Implement lazy loading for unused translations
Optimize CDN caching strategy
Consider using translation API instead of static files (for frequently updated content)
Implement service worker caching for translations (PWA)

Quality Assurance

Schedule regular translation reviews
Collect user feedback on translation quality
A/B test different translations
Monitor user engagement per language
Update translations based on user feedback

Scaling

Plan for adding new languages
Document process for adding new locales
Optimize infrastructure for more languages
Consider translation memory and glossary
Plan for regional variants (en-US vs en-GB, es-ES vs es-MX)

Common Deployment Issues

Missing Translations

Symptom: Users see translation keys instead of translated text Fix:

Check translation files are deployed
Verify CDN cache is cleared
Check for typos in translation keys
Verify fallback locale is configured

Broken Layout

Symptom: UI breaks with certain languages Fix:

Test with longest translations (German, Finnish)
Add CSS overflow handling
Use flexible layouts (flexbox, grid)
Test with real content, not Lorem Ipsum

SEO Issues

Symptom: Locale pages not indexed or duplicate content warnings Fix:

Verify hreflang tags are correct
Check canonical URLs
Verify sitemap includes all locales
Check robots.txt doesn't block locale URLs

Performance Issues

Symptom: Slow page load for certain locales Fix:

Optimize translation file size
Enable CDN caching
Implement lazy loading
Check for large locale-specific assets

Encoding Issues

Symptom: Special characters display as � or garbled text Fix:

Verify UTF-8 encoding for all files
Check database collation
Verify HTTP headers specify UTF-8
Check for BOM issues

Emergency Contacts

Document on-call rotation for i18n issues
Create escalation path for critical issues
Document contact info for translation team
Set up emergency communication channel (Slack, PagerDuty)
Document rollback authority and process

Post-Mortem

After deployment, conduct a post-mortem:

What went well?
What could be improved?
Were there any unexpected issues?
How long did deployment take?
Were there any rollbacks?
What lessons were learned?
Update deployment checklist based on learnings

Pro Tips:

Deploy during low traffic: Schedule i18n deployments during off-peak hours to minimize impact.
Test in production-like environment: Staging should mirror production as closely as possible.
Monitor closely: Watch error logs and analytics closely for the first 24 hours after deployment.
Have a rollback plan: Always be ready to rollback if something goes wrong.
Communicate with team: Keep team informed of deployment status and any issues.
Document everything: Document deployment process, issues, and resolutions for future reference.
Automate where possible: Use CI/CD to automate deployment and reduce human error.
Test with real users: Beta test with native speakers before full launch.
Plan for growth: Design deployment process to scale to 50+ languages.
Learn from each deployment: Conduct post-mortems and continuously improve the process.