Implement Internationalization Without Scattering Text
Overview
An internationalization design separates message keys from presentation and treats locale as structured application context.
Separate messages from code
Store user-facing messages in locale catalogs rather than scattering literal strings through templates and scripts. Use stable message keys and interpolation parameters. Avoid building sentences by concatenating translated fragments because word order and grammar vary by language.
Format data using locale-aware APIs
Dates, numbers, currencies, and plural forms differ by locale. Use established formatting APIs and store timestamps and numeric values in canonical forms. Do not store a formatted currency string as the source of truth for a monetary amount.
Decide how locale is selected
A site may use a locale path such as /en/ or /tr/, a subdomain, or a user preference. Make canonical URLs and language alternates consistent. Avoid relying solely on IP geolocation; allow users to choose and retain a language. Set the document language and direction correctly.
Test beyond translated words
Test long labels, plural categories, right-to-left layouts, date boundaries, sorting, search, and fallback behavior when a translation is missing. Review translated content in context. Internationalization is an architectural capability, not a final find-and-replace task.
Implementation checklist
- Define the expected behavior and supported environments.
- Keep security, accessibility, and failure states in the design.
- Measure the result with representative user journeys.
- Document operational assumptions and review them after changes.