JSON for Internationalization: Building Multilingual Applications

JSON is the most popular format for managing translations in modern web applications. This guide shows you how to structure and use i18n JSON files effectively.

Basic Translation Structure

{
  "home": {
    "title": "Welcome",
    "subtitle": "Build amazing things",
    "cta": "Get Started"
  },
  "nav": {
    "about": "About",
    "contact": "Contact",
    "blog": "Blog"
  }
}

Nested vs Flat Structure

Nested (easier to organize):

{
  "user": {
    "profile": {
      "title": "My Profile",
      "edit": "Edit Profile"
    }
  }
}

Flat with dot keys (easier for translators):

{
  "user.profile.title": "My Profile",
  "user.profile.edit": "Edit Profile"
}

Pluralization

Handle singular/plural forms:

{
  "items": {
    "zero": "No items",
    "one": "1 item",
    "other": "{count} items"
  }
}

Interpolation

Insert dynamic values:

{
  "welcome": "Hello, {name}!",
  "lastSeen": "Last seen {days} days ago",
  "cartTotal": "Total: {amount}"
}

Organizing Translation Files

messages/
  ├── en/
  │   ├── common.json      — Shared strings
  │   ├── home.json        — Homepage
  │   ├── dashboard.json   — Dashboard page
  │   └── errors.json      — Error messages
  └── zh/
      ├── common.json
      ├── home.json
      ├── dashboard.json
      └── errors.json

Popular i18n Libraries

next-intl — Next.js internationalization (used by this site!)

react-i18next — React ecosystem standard

vue-i18n — Vue.js internationalization

i18next — Framework-agnostic, works everywhere

Best Practices

Use keys, not English text as keys — "greeting" not "Hello"

Keep translations in sync — Same keys across all languages

Fallback language — Always have a default language

Context over literal translation — Translate meaning, not words

Use namespaces — Group by feature or page

This very site uses JSON for bilingual support (English and Chinese) with next-intl!