A SaaS internationalization checklist covers the engineering work required before translation can begin: externalizing all user-facing strings into resource files, switching to UTF-8 encoding across the full stack, replacing hardcoded date, number, and currency formats with locale-aware functions, building flexible layouts that survive text expansion, implementing proper locale detection and URL structure, and preparing the database and APIs to store and serve locale-specific data. Internationalization, or i18n, is architecture, not translation. Skipping it and translating directly into an unprepared codebase typically costs three to five times more than doing the engineering work first, because every skipped step surfaces later as a production bug.
1. What i18n Actually Means, and Why It Comes Before Localization
Internationalization, abbreviated i18n because there are 18 letters between the i and the n, is the process of designing and building software so it can support multiple languages, regions, and cultural conventions without requiring code changes for every new locale added. It is an architecture decision, not a translation task.
Localization, or l10n, is what happens after i18n is in place: adapting the internationalized product for a specific market, with actual translated content, local formatting, and cultural adjustments. The relationship is sequential and non-negotiable. You cannot localize a product efficiently that was never internationalized, in the same way you cannot install plumbing in a house after the concrete foundation has already been poured without a plan for pipes.
The Cost of Skipping i18n
Teams that skip internationalization and translate directly into an unprepared codebase consistently report costs three to five times higher than teams that complete the engineering work first. The reason is structural. Every hardcoded string, every fixed-width button, every manually formatted date has to be found and fixed individually, usually after a translator or a real user has already discovered the problem in production. Delaying i18n does not avoid the cost. It moves the cost later, attaches it to a live release, and compounds it with every new feature shipped in the meantime.
This compounding effect is the part teams most often underestimate. A SaaS product that skips i18n and ships six more features before addressing it now has six more features worth of hardcoded strings, fixed layouts, and manual formatting to retrofit, on top of the original backlog.
→ Read the full framework: The Complete Guide to SaaS Localization (2026), Pillar Article
→ SaaS localization vs. software localization: what’s the same, what’s different, and why it matters
2. String Externalization: The First and Most Important Step
String externalization means moving every piece of user-facing text out of the application code and into external resource files, typically JSON, YAML, PO, or XLIFF format, so that a translator can produce a new language version without a developer touching the codebase.
What Externalization Looks Like in Practice
Instead of writing a button label directly into a component, the component references a translation key, and the actual text lives in a separate resource file per locale. A button that reads Get started in the English file becomes an entry keyed as cta.get_started, and the component calls that key rather than containing the literal English string. Every supported locale then has its own resource file mapping the same set of keys to the appropriate translated text.
Where Hardcoded Strings Hide
The obvious place to look for hardcoded strings is UI components, but they frequently hide in less obvious places that get missed during a rushed audit:
• Error handlers and exception messages, which are often written quickly during development and rarely revisited
• Email and notification templates, especially transactional emails built outside the main application codebase
• Validation messages attached directly to form fields
• Text baked into images, icons, or generated PDFs, which cannot be translated through a standard string pipeline at all
• Third-party widget or plugin configuration text that the core team assumes is out of scope
• Log messages and admin-only interfaces, which teams often deliberately leave in English but should still consciously decide on, not overlook by accident
A Stable Key Convention
String keys need a naming convention that survives refactors and stays stable across releases, since translation memory and glossary systems rely on consistent keys to track and reuse translations over time. A common pattern groups keys by feature or screen, such as billing.invoice.download_button or onboarding.step_two.headline, which keeps the resource files organized and makes it obvious to a translator where in the product a given string appears.
| Linguidoor Insight In our i18n audits, transactional emails and error messages are the two categories most commonly missed during string externalization, because they are built by different teams on different timelines than the core product UI. Both deserve an explicit line item in the audit, not an assumption that the main externalization pass already covered them. |
3. Character Encoding: Unicode Everywhere, No Exceptions
UTF-8 encoding needs to be consistent across the entire application stack: HTML meta tags, HTTP headers, API request and response bodies, database columns, and file storage. A single layer using a legacy encoding, such as Latin-1 or Windows-1252, creates character rendering failures the moment non-Latin or accented characters pass through it.
Why This Matters More Than It Seems
Encoding problems are easy to miss during development, because English text encoded incorrectly often still displays correctly by coincidence. The problem only becomes visible once real translated content, particularly Cyrillic, Arabic, or CJK (Chinese, Japanese, Korean) scripts, passes through the affected layer. The typical symptom is garbled text, question marks in place of characters, or empty rectangular boxes sometimes called tofu, appearing in production for specific languages while everything looks fine in English testing.
This is exactly why encoding should be verified as part of the i18n audit rather than discovered after a translated release ships. A database column created years ago with a Latin-1 default, buried under several layers of ORM abstraction, is a common and easy-to-miss source of this failure.
What to Check
• HTML documents declare UTF-8 explicitly in the meta charset tag
• HTTP response headers specify UTF-8 as the character encoding
• Database tables and columns storing user-facing text use a UTF-8 compatible collation, not a legacy default inherited from an older schema
• API request and response bodies preserve UTF-8 through every intermediate service, including any caching or logging layer
• File exports, such as CSV or PDF generation, encode output correctly rather than defaulting to ASCII or Latin-1
→ Date, time, currency, and number formatting in SaaS: the developer’s guide to locale-aware data display
4. Locale-Aware Formatting: Dates, Numbers, Currency, and Pluralization
Dates, numbers, currencies, and plural forms all follow different conventions across locales, and a product that formats these manually with hardcoded logic will produce incorrect or confusing output the moment it serves a user outside its original market.
Dates, Numbers, and Currency
A date written as 06/09/2026 means June 9 to a US-formatted reader and September 6 to almost everyone else. Manual string concatenation that assumes a specific date format, a specific decimal separator, or a hardcoded currency symbol will produce this kind of ambiguity or outright error the moment a non-default locale reaches that code path.
The fix is to route every date, number, and currency value through a locale-aware formatting function, such as the Intl API built into modern browsers and JavaScript runtimes, or an equivalent library in other languages, rather than building format strings by hand. The underlying data stays the same. Only the display formatting changes based on the active locale.
Pluralization Rules Are Not Universal
English has two plural forms: one item, and everything else. Many languages have more. Arabic has six grammatical plural categories. Russian and Polish each have four. A hardcoded conditional that checks whether a count equals one, and otherwise appends an s, will produce grammatically broken output in every language with a different plural structure.
The correct approach uses a pluralization-aware i18n library that selects the right plural category based on both the count and the active locale’s grammar rules, rather than a manually coded English-only assumption.
Named Placeholders Instead of Concatenation
Dynamic strings built by concatenating fragments, such as joining a greeting, a username variable, and a fixed suffix into one sentence, break down in translation because word order is not consistent across languages. German frequently places the verb at the end of a clause. Japanese follows a subject-object-verb structure that differs from English. A translator handed three disconnected fragments cannot reliably reconstruct a grammatically correct sentence in the target language.
Complete sentence templates with named placeholders solve this: a single string such as Hello, {username}! You have {count} messages, handed to the translator as one unit, can be reordered freely to match the grammar of the target language, because the placeholder names carry meaning independent of their position in the sentence.
5. Layout and Design: Building for Text Expansion and RTL
Even a perfectly externalized, correctly encoded, properly formatted product will still break visually if the layout itself was designed around the assumption that all text is roughly the length of its English source.
Designing for Text Expansion
German and Finnish labels commonly run 30 to 50 percent longer than their English equivalents. French and Russian typically expand by 15 to 35 percent. A safe general rule is to design UI containers, particularly buttons, navigation items, and form labels, to accommodate at least 50 percent more characters than the English source text without breaking, clipping, or forcing awkward line wraps.
In practice, this means replacing fixed pixel widths with minimum widths, using flexible layout systems such as flexbox or CSS grid that reflow naturally, and avoiding overflow: hidden on any container that holds translatable text unless a deliberate, visible truncation pattern is in place.
Right-to-Left Language Support
Arabic and Hebrew read right to left, and supporting them properly is a full layout mirror, not a text-alignment change. Navigation placement, icon direction, breadcrumb order, and the entire visual hierarchy need to flip for RTL locales. This needs to be planned into the component architecture from the start, using CSS logical properties (such as margin-inline-start rather than margin-left) so that direction-aware styling is handled automatically rather than requiring a duplicate RTL stylesheet maintained by hand.
Font and Script Support
Fonts chosen for an English-only product frequently do not include the character sets needed for Arabic, Thai, Vietnamese, or CJK scripts. This needs to be verified explicitly against every target script during the i18n phase, not discovered after a translated build renders with missing glyphs or fallback system fonts that clash with the rest of the design.
→ RTL support for SaaS products: how to adapt your platform for Arabic and Hebrew speaking users
6. Locale Detection and URL Architecture
A SaaS product needs a coherent strategy for determining which locale to serve a given user, and for structuring URLs so that both users and search engines can navigate between language versions predictably.
How Locale Detection Actually Works
Most production systems combine several signals rather than relying on just one. The Accept-Language HTTP header provides an initial guess based on browser settings on a user’s first visit. That guess is then encoded into the URL, which makes the choice explicit, shareable, and crawlable by search engines. Finally, an explicit language selector lets the user override the detected locale, with that preference stored in a cookie or user profile for return visits.
The single most important principle in locale detection is that automatic detection is an inference, not a fact, and the interface must always give the user an easy, visible way to override it. A user whose browser is set to French but who actually wants to work in English should never be permanently locked into a mismatched locale.
URL Structure Options
Three common patterns exist for encoding locale into a URL, each with different tradeoffs:
| Pattern | Example | Tradeoff |
| Subdirectory | example.com/de/pricing | Simplest to implement, consolidates domain authority for SEO, the most common choice for SaaS |
| Subdomain | de.example.com/pricing | Allows separate hosting or infrastructure per locale, splits SEO authority across subdomains |
| ccTLD | example.de/pricing | Strongest local geotargeting signal, highest infrastructure and maintenance overhead |
For most SaaS products, subdirectories are the practical default: locale is explicit and visible in the URL, it is straightforward for modern frameworks to implement at the routing layer, and it keeps SEO authority consolidated under a single domain rather than fragmented across subdomains or country-code domains.
Handling Regional Language Variants
Some languages split into distinct regional variants that are not interchangeable. Simplified Chinese, used in mainland China and Singapore, and Traditional Chinese, used in Taiwan, Hong Kong, and Macao, differ in far more than character set, extending to vocabulary choices as well. A locale-matching system that treats a request for zh-TW as equivalent to zh-Hans will produce output that is immediately and obviously wrong to a native reader. Locale negotiation logic needs to handle these distinctions explicitly rather than falling back to a naive exact-match or first-two-letter comparison.
7. Database and API Readiness
Internationalization extends below the UI layer into how data is stored, structured, and served, and this layer is frequently the last one teams think to check.
Locale-Aware Data Storage
If a user’s locale preference is stored as a bare two-letter language code, such as es, without a regional qualifier, the system cannot distinguish between the different conventions used across Spanish-speaking markets, or correctly select between Simplified and Traditional Chinese. Storing full locale identifiers, such as es-MX or zh-Hant, rather than bare language codes, preserves the information needed to serve genuinely correct formatting and content downstream.
Any user-facing text stored in the database, such as user-generated content, custom labels, or configuration values, needs the same UTF-8 consistency required everywhere else in the stack, verified at the schema level rather than assumed.
API Design for Multi-Locale Content
APIs that serve content to a multi-locale frontend need an explicit locale parameter on relevant endpoints, rather than inferring locale implicitly from request headers alone, since implicit inference makes caching, testing, and debugging significantly harder. Response payloads that mix locale-specific formatted values, such as a pre-formatted currency string, with raw underlying data give frontend clients the flexibility to reformat correctly if a display requirement changes, rather than forcing a backend round trip for a formatting fix.
Fallback Behavior
Translations for a specific locale are not always complete, particularly for newly launched languages or recently shipped features. A fallback chain defines what the system should show when a specific translation is missing: falling back from a regional variant to the base language, and from the base language to a default such as English, rather than displaying a raw translation key or an empty string to the user. This fallback behavior needs to be configured deliberately as part of the i18n setup, not left to whatever the library’s default happens to do.
| Common Mistake to Avoid Storing locale as a bare language code (es, pt, zh) instead of a full locale identifier (es-MX, pt-BR, zh-Hant). This single decision, made early and rarely revisited, is one of the most common causes of formatting and content mismatches we find during i18n audits, and it is expensive to correct retroactively once real user data already exists in the simplified format. |
8. The Complete i18n Checklist
A consolidated checklist covering every area addressed in this guide, organized for a team preparing to run its own i18n audit before starting a localization project.
| Area | What to Verify |
| String externalization | All user-facing text lives in resource files, including error messages, emails, and validation text, not just core UI components |
| Key naming | String keys follow a stable, feature-grouped convention that survives refactors and releases |
| Character encoding | UTF-8 is consistent across HTML, HTTP headers, database, APIs, and file exports |
| Date and number formatting | All dates, numbers, and currencies render through a locale-aware formatter, never hardcoded format strings |
| Pluralization | The i18n library handles locale-specific plural rules rather than a hardcoded singular or plural check |
| String assembly | Dynamic strings use complete sentence templates with named placeholders, not concatenated fragments |
| Layout flexibility | UI containers accommodate at least 50 percent more characters than the English source without breaking |
| RTL readiness | Layout uses CSS logical properties and is designed to fully mirror for Arabic and Hebrew, not just flip text alignment |
| Font and script support | Fonts in use support every target script, verified explicitly, not assumed from the English build |
| Locale detection | Combines header-based inference, URL encoding, and an explicit, always-visible user override |
| URL structure | A defined pattern (subdirectory, subdomain, or ccTLD) is chosen deliberately, with regional variants like zh-Hans and zh-Hant handled correctly |
| Database locale storage | User locale preference is stored as a full identifier (es-MX, not es), and stored content is UTF-8 consistent |
| API locale handling | Locale is passed explicitly rather than inferred silently, and fallback behavior is configured deliberately |
9. The Linguidoor Approach to i18n Readiness
Linguidoor works with SaaS engineering and product teams before translation begins, because the readiness of the codebase determines the cost, timeline, and quality of everything that follows.
A Structured Audit, Not a Generic Checklist Handoff
Rather than handing a client a generic checklist and leaving the interpretation to their engineering team, we run a structured audit against the client’s actual codebase, covering string externalization, encoding, formatting, layout flexibility, locale detection, and database readiness. The output is a written report prioritizing issues by the cost and risk they carry if left unresolved, so engineering effort is spent where it matters most first.
Working Alongside Engineering, Not Just Reporting Issues
Identifying i18n gaps is only useful if they get fixed correctly. We work directly alongside client engineering teams during the remediation phase, reviewing string externalization patterns, CSS architecture for layout flexibility, and locale detection logic, rather than simply handing over a list of problems and disappearing until translation begins.
Pseudo-Localization Before Real Translation Spend
Before committing budget to real translation, we run pseudo-localization tests, artificially expanding and modifying source strings to simulate real translated text, which surfaces hardcoded strings and layout breakage at zero translation cost. This step alone consistently catches issues that would otherwise only surface once real, paid translation work is already underway.
A Foundation Built for Every Future Language, Not Just the First
The goal of an i18n engagement is not just readiness for the first target language. A properly internationalized product should make adding a fifth or tenth language a translation and content exercise, not another round of engineering work. We scope the i18n phase with this multi-language future in mind, so clients do not pay for the same architectural fixes repeatedly as they expand into new markets.
| Ready for an i18n Audit? If your SaaS product is preparing for its first localized market, or if a previous localization effort ran into layout and formatting problems, Linguidoor can run a structured i18n audit against your actual codebase and give you a prioritized, actionable remediation plan. Contact Linguidoor to scope your i18n readiness assessment. |
10. Frequently Asked Questions
How long does i18n take for an existing SaaS product?
The technical groundwork, primarily string externalization and layout flexibility fixes, typically takes a development team anywhere from a few days to several weeks, depending on the size and age of the codebase. Products that were never built with i18n in mind, with deeply embedded hardcoded strings and fixed layouts throughout, take longer than products that externalized strings from the start but never formalized the rest of the i18n layer.
Can we start translating before i18n is fully complete?
Technically yes, but it is not advisable. Translating into a codebase with hardcoded strings, fixed layouts, or manual date formatting produces translated content that will not display correctly, requiring rework once the underlying issues are fixed. The three to five times cost multiplier commonly cited for skipping i18n comes specifically from this pattern: translation work redone after the fact once engineering catches up.
Do we need full RTL support if we are not launching in Arabic or Hebrew yet?
Not immediately, but it is worth deciding deliberately rather than by default. Using CSS logical properties instead of directional properties from the start costs very little extra effort during initial development and avoids a much larger retrofit later if Arabic or Hebrew markets are added to the roadmap. Teams that are confident RTL languages will never be a target market can reasonably deprioritize this, as long as the decision is explicit.
What is the difference between i18n and l10n in practical terms?
i18n is engineering work performed once, by developers, that makes the product capable of supporting any locale without further code changes. l10n is content and design work performed repeatedly, once per target market, that fills the internationalized architecture with actual translated text, locale-specific formatting, and cultural adaptation. A well-built i18n foundation makes each subsequent l10n effort faster and cheaper, since the same architecture supports every new language.
How do we know if our product’s i18n is actually ready before starting a localization project?
Pseudo-localization is the most reliable low-cost test. Running source strings through a script that expands their length and adds accented characters, then checking the interface for overflow, clipping, or untranslated text, reveals most i18n gaps immediately, without spending any budget on real translation. Any string that does not change under pseudo-localization is hardcoded and was missed during string externalization.
Continue Reading
RTL support for SaaS products: how to adapt your platform for Arabic and Hebrew speaking users
SaaS localization vs. software localization: what’s the same, what’s different, and why it matters