Skip to content
Complete Guide

Internationalization and Localization: The Complete Guide

Everything an engineering team needs to ship software in more than one language: the core concepts, the file formats, the rollout process, the mistakes that cost the most, and how to test all of it.

Get Started FreeRead the Docs

i18n · once

Internationalization (i18n)

  • Locale Identifiers (BCP 47)
  • Unicode & UTF-8
  • Translation Keys
  • Pluralization (ICU)
t("cart.items", { count })

L10n · per locale

Localization (L10n)

  • tr-TRreviewed
  • de-DEreviewed
  • ja-JPin review
  • ar-EGrtl · queued

Foundations

The Concepts Every i18n System Rests On

Six ideas do most of the work. Get them right and the rest of your setup follows. Get them wrong and you rewrite it later.

Internationalization (i18n)

Internationalization is the engineering work that makes your product capable of speaking any language. You do it once, in the codebase, and it stays language neutral: no string is written into a component, every date and number goes through a locale-aware formatter, and every layout survives text that grows by 40 percent.

In practice that means externalizing text into resource files, giving every string a stable key, handling plural and gender rules with ICU MessageFormat, and using CSS logical properties so a right-to-left locale does not need its own stylesheet.

The cost of skipping it is architectural. Adding a second language to a product that was never internationalized is a refactor of every screen, not a translation project.

Localization (L10n)

Localization is the content work you repeat for every market you enter. It starts with translation, then adds what translation alone does not cover: currency and address formats, legal wording, examples that make sense locally, and imagery that reads correctly in that culture.

Localization is also a review process. Someone who speaks the language decides whether the tone matches your brand, whether the term for a feature is the one users actually search for, and whether a machine translation is good enough to ship.

Because it repeats per locale, localization is where tooling pays off. The faster a string moves from merged code to reviewed translation, the more markets one team can support.

  • Locale Identifiers (BCP 47)

    BCP 47 tags like en-US or zh-Hans-CN encode language, script, and region. They are the foundation of every i18n system and determine which translations, formats, and rules apply.

  • Unicode & UTF-8

    Unicode assigns a unique code point to every character in every script. UTF-8 is the dominant encoding on the web and ensures text renders correctly regardless of language.

  • Translation Keys

    Translation keys are stable identifiers that map to locale-specific strings. They decouple your source code from translatable content, enabling parallel development and translation.

  • Pluralization (ICU)

    Languages have different plural rules — English has two forms, Arabic has six. ICU MessageFormat handles plurals, gender, and select expressions in a single syntax.

  • RTL Support

    Arabic, Hebrew, and other scripts read right-to-left. RTL support requires mirroring layouts, flipping icons, and using CSS logical properties instead of left/right.

  • Date / Number / Currency

    Dates, numbers, and currencies vary by locale. The Intl API and libraries like date-fns provide locale-aware formatting so 1,000.50 renders as 1.000,50 in German.

File Formats

Choosing a Translation File Format

Your platform decides most of this choice, but the format also decides how plurals work, what context translators can see, and which tools can read your files.

JSON

.json

React · Vue · Angular

Most popular for web apps (React, Vue, Angular). Human-readable, supports nesting for organized key structures. No built-in pluralization standard, so libraries like ICU MessageFormat fill the gap.

XLIFF

.xlf

TMS interchange

XML-based industry standard for translation exchange between tools. Supported by all professional TMS platforms. Verbose but feature-rich, with built-in support for notes, state tracking, and metadata.

PO/POT (Gettext)

.po / .pot

Python · PHP · Ruby

Classic open-source format used in Python, PHP, and Ruby ecosystems. Built-in plural support with dedicated plural forms syntax. Widely supported by translators and translation tools.

ARB

.arb

Flutter · Dart

Application Resource Bundle is the Flutter and Dart standard format. JSON-based with ICU message syntax support, enabling plurals and selects natively. Used by Flutter's gen-l10n tooling.

.strings / .stringsdict

.strings

iOS · macOS

Apple platform native formats for iOS and macOS development. .strings handles simple key-value pairs while .stringsdict uses XML plist structure for pluralization rules.

.resx

.resx

.NET · C#

.NET resource file format used for C# and VB.NET applications. XML-based with strong Visual Studio tooling integration. Supports typed resources for strings, images, and other assets.

Implementation

How an i18n Implementation Actually Runs

Four steps from a single-language codebase to translations that ship continuously.

  1. Audit Your CodebaseIdentify every hardcoded string, date format, and locale-dependent pattern. Map which components and pages contain user-facing text that needs extraction.
  2. Externalize StringsMove all user-facing text into structured resource files (JSON, XLIFF, or PO). Replace inline strings with translation function calls that reference keys.
  3. Choose Your ToolsSelect an i18n library for your framework, a translation management system (TMS) for collaboration, and decide between human, AI, or hybrid translation workflows.
  4. Integrate & ShipWire your i18n library into routing and rendering, connect your TMS to CI/CD for automatic syncing, and deploy locale bundles via CDN for fast delivery.

Production Readiness Checklist

Run through this before you call the first locale done. Every item here is something teams usually discover in production instead.

  • All user-facing strings externalized to resource files
  • Locale detection implemented (browser, URL, user preference)
  • Pluralization handled with ICU MessageFormat for all target languages
  • Date, time, number, and currency formatting uses Intl API or equivalent
  • RTL layout support tested with CSS logical properties
  • Fallback locale configured for missing translations
  • Translation keys follow a consistent naming convention
  • CI pipeline validates no missing or unused translation keys

Tooling

What to Look for in a Translation Management System

A TMS is where translations live between your repository and your users. Four things separate the ones that speed a team up from the ones that add another handoff.

  • Developer Integration

    Evaluate CLI tools, SDK support, Git-based workflows, and CI/CD hooks. The best TMS platforms integrate directly into your development pipeline so translations stay in sync with code changes automatically.

  • Translation Memory

    Translation memory stores previously approved translations and suggests them for similar or identical strings. This reduces translation cost, speeds up turnaround, and maintains consistency across your product.

  • Collaboration Features

    Look for reviewer workflows, inline comments, shared glossaries, and approval chains. These features enable translators, reviewers, and developers to work together without bottlenecks or miscommunication.

  • AI and Automation

    Modern TMS platforms offer machine translation suggestions, automated quality checks, batch operations, and smart routing. AI-assisted workflows reduce manual effort while maintaining translation quality.

Quality

The Four Mistakes That Cost the Most

Each one is cheap to avoid on day one and expensive to unwind after launch.

  • String Concatenation

    Building sentences by concatenating fragments breaks in languages with different word order. Use ICU MessageFormat with placeholders instead.

  • Hardcoded Strings

    Embedding user-facing text directly in source code makes translation impossible without code changes. Externalize every string from day one.

  • Ignoring Plurals

    Simple if/else for singular/plural only works in English. Many languages have multiple plural forms that require proper ICU plural rules.

  • Translation as Afterthought

    Bolting on i18n after launch means expensive refactoring. Designing for internationalization from the start saves time and prevents architectural debt.

How to Test Localized Software

Translation bugs rarely look like exceptions. They look like a clipped button, a sentence in the wrong order, or a date nobody in that country reads. Testing has to be deliberate.

  • Pseudo-localization catches hardcoded strings and truncation before any real translation exists
  • Per-locale visual regression tests catch layout breaks from longer text and right-to-left mirroring
  • CI checks fail the build on missing keys, unused keys, and broken ICU placeholders
  • Native reviewers check tone, terminology, and cultural fit on the strings users see most
  • Text expansion tests run German and Finnish copy through the tightest components in your UI

By framework

Framework Guides

The concepts above are universal. The wiring is not, so pick your stack for the setup, routing, and rendering details.

Reactreact-intl, react-i18next, and FormatJS patternsNext.jsApp Router, middleware, and server component i18nVuevue-i18n composition API and SFC integrationAngularBuilt-in i18n, ngx-translate, and TranslocoSveltesvelte-i18n, SvelteKit routing, and storesFlutterintl package, ARB files, and gen-l10n toolingReact Nativei18next, Expo localization, and native modulesNuxt@nuxtjs/i18n module with auto-routing

FAQ

Frequently Asked Questions About i18n and L10n

The questions engineering teams ask before their first localized release.

What is Internationalization?A plain definition of internationalization and what it coversWhat is Localization?What localization includes beyond translating textLocalization vs InternationalizationThe two processes side by side, and where each one startsSoftware LocalizationLocalizing an application end to end, from strings to releaseBest i18n LibraryHow the major i18n libraries compare, per framework

Start shipping in every language

Connect a repository or upload your JSON files, and get your first locale live today.

Get Started FreeRead the Docs