JSON (i18next) Files: Complete Guide to i18next JSON Format

What Is i18next JSON Format?

i18next is one of the most popular internationalization frameworks for JavaScript, used by thousands of applications worldwide. The i18next JSON format is the standard way to store translation strings for applications using i18next, including React, Vue.js, Angular, Node.js, and many other JavaScript frameworks.

i18next JSON files store translation keys and values in a structured format that supports features like interpolation, pluralization, nesting, context variants, and more.

Why AZbox Supports i18next JSON Format

At AZbox, we recognize that i18next is the go-to localization solution for JavaScript developers. That’s why AZbox fully supports i18next JSON file import and export, allowing you to:

• Import existing i18next JSON files directly into your AZbox project
• Export translations back to i18next JSON format for use in your app
• Support all i18next JSON versions (v1, v2, v3, v4)
• Manage translations with our powerful cloud-based platform
• Collaborate with translators who can work directly with your content
• Update over-the-air without rebuilding your application

i18next JSON Versions

i18next has evolved over time, and there are four major JSON format versions. AZbox supports all of them:

Version	Key Feature	Plural Format
v4 (Current)	ICU-compatible plurals	_one, _other, _few, etc.
v3	Simplified plurals	_plural suffix
v2	Legacy plural indices	_0, _1, _2, etc.
v1	Original format	__value__ interpolation

i18next JSON v4 (Recommended)

The latest and recommended format, v4 uses ICU-compatible plural suffixes based on the Intl.PluralRules API:

{
  "appTitle": "My Application",
  "welcome": "Welcome to our app!",
  
  "keyDeep": {
    "inner": "Nested value"
  },
  
  "keyNesting": "Reuse: $t(keyDeep.inner)",
  
  "greeting": "Hello, {{name}}!",
  
  "greetingUnescaped": "Hello, {{- name}}!",
  
  "formattedValue": "Price: {{value, currency}}",
  
  "context_male": "He is a developer",
  "context_female": "She is a developer",
  
  "itemCount_one": "{{count}} item",
  "itemCount_other": "{{count}} items",
  
  "arabicPlural_zero": "No items",
  "arabicPlural_one": "One item",
  "arabicPlural_two": "Two items",
  "arabicPlural_few": "A few items",
  "arabicPlural_many": "Many items",
  "arabicPlural_other": "{{count}} items",
  
  "arrayValue": ["First", "Second", "Third"],
  
  "objectValue": {
    "title": "Section Title",
    "description": "Section description"
  }
}

v4 Plural Suffixes

Suffix	Usage	Example Languages
_zero	Zero items	Arabic, Latvian
_one	Singular	English, Spanish, German
_two	Dual form	Arabic, Welsh, Slovenian
_few	Few items	Russian, Polish, Czech
_many	Many items	Russian, Arabic, Polish
_other	Default/general plural	All languages

i18next JSON v3

Version 3 uses simplified _plural suffix for plural forms:

{
  "appTitle": "My Application",
  "welcome": "Welcome to our app!",
  
  "greeting": "Hello, {{name}}!",
  
  "context_male": "He is a developer",
  "context_female": "She is a developer",
  
  "itemCount": "{{count}} item",
  "itemCount_plural": "{{count}} items",
  
  "arabicPlural_0": "No items",
  "arabicPlural_1": "One item",
  "arabicPlural_2": "Two items",
  "arabicPlural_3": "A few items",
  "arabicPlural_4": "Many items",
  "arabicPlural_5": "{{count}} items"
}

To use v3 format in i18next:

i18next.init({
  compatibilityJSON: 'v3'
});

i18next JSON v2

Version 2 uses numeric indices for complex plural forms:

{
  "appTitle": "My Application",
  
  "greeting": "Hello, {{name}}!",
  
  "itemCount": "{{count}} item",
  "itemCount_plural": "{{count}} items",
  
  "arabicPlural_0": "No items",
  "arabicPlural_1": "One item",
  "arabicPlural_2": "Two items",
  "arabicPlural_3": "A few items",
  "arabicPlural_11": "Many items",
  "arabicPlural_100": "{{count}} items"
}

i18next JSON v1

The original format uses double underscores for interpolation:

{
  "appTitle": "My Application",
  
  "greeting": "Hello, __name__!",
  
  "greetingHTML": "Hello, __nameHTML__!",
  
  "itemCount": "__count__ item",
  "itemCount_plural": "__count__ items"
}

Key Features of i18next JSON

1. Interpolation

Insert dynamic values into your translations:

{
  "welcome": "Welcome, {{username}}!",
  "orderStatus": "Order #{{orderId}} is {{status}}",
  "score": "You scored {{points}} points"
}

Usage in JavaScript:

t('welcome', { username: 'John' })
// Output: "Welcome, John!"

t('orderStatus', { orderId: '12345', status: 'shipped' })
// Output: "Order #12345 is shipped"

2. Unescaped Interpolation

For HTML content, use the {{- value}} syntax:

{
  "richContent": "Welcome to {{- companyName}}",
  "htmlMessage": "Click {{- link}} for more info"
}

Usage:

t('richContent', { companyName: '<strong>AZbox</strong>' })
// Output: "Welcome to <strong>AZbox</strong>"

3. Nesting

Reuse translations within other translations:

{
  "appName": "AZbox",
  "welcome": "Welcome to $t(appName)!",
  "tagline": "$t(appName) - Localization made easy"
}

Output:

t('welcome')    // "Welcome to AZbox!"
t('tagline')    // "AZbox - Localization made easy"

4. Context

Create variants based on context (gender, formality, etc.):

{
  "friend": "A friend",
  "friend_male": "A boyfriend",
  "friend_female": "A girlfriend",
  
  "greeting": "Hello",
  "greeting_formal": "Good day",
  "greeting_informal": "Hey"
}

Usage:

t('friend', { context: 'male' })     // "A boyfriend"
t('friend', { context: 'female' })   // "A girlfriend"
t('greeting', { context: 'formal' }) // "Good day"

5. Pluralization

Handle singular and plural forms:

{
  "message_one": "You have {{count}} message",
  "message_other": "You have {{count}} messages",
  
  "item_one": "{{count}} item in cart",
  "item_other": "{{count}} items in cart"
}

Usage:

t('message', { count: 1 })  // "You have 1 message"
t('message', { count: 5 })  // "You have 5 messages"

6. Formatting

Apply formatting to interpolated values:

{
  "price": "Total: {{value, currency(USD)}}",
  "date": "Created on {{date, datetime}}",
  "percentage": "Progress: {{value, number(percent)}}"
}

7. Nested Objects

Organize translations hierarchically:

{
  "nav": {
    "home": "Home",
    "about": "About Us",
    "contact": "Contact",
    "products": {
      "list": "All Products",
      "featured": "Featured",
      "sale": "On Sale"
    }
  },
  "auth": {
    "login": "Sign In",
    "logout": "Sign Out",
    "register": "Create Account"
  }
}

Usage:

t('nav.home')              // "Home"
t('nav.products.featured') // "Featured"
t('auth.login')            // "Sign In"

8. Arrays

Store multiple values:

{
  "colors": ["Red", "Green", "Blue"],
  "sizes": ["Small", "Medium", "Large", "X-Large"]
}

Usage:

t('colors', { returnObjects: true })
// ["Red", "Green", "Blue"]

File Naming Convention

i18next JSON files typically follow this naming structure:

locales/
├── en/
│   ├── translation.json    (default namespace)
│   ├── common.json         (common namespace)
│   └── errors.json         (errors namespace)
├── es/
│   ├── translation.json
│   ├── common.json
│   └── errors.json
└── fr/
    ├── translation.json
    ├── common.json
    └── errors.json

Or using a flat structure:

locales/
├── en.json
├── es.json
├── fr.json
└── de.json

Importing i18next JSON to AZbox

Step 1: Prepare Your JSON Files

Ensure your files are valid JSON and follow i18next conventions:

locales/
├── en/
│   └── translation.json
├── es/
│   └── translation.json
└── fr/
    └── translation.json

Step 2: Import via AZbox Dashboard

1. Log in to your AZbox dashboard
2. Navigate to your project
3. Go to Import/Export section
4. Select Import and choose JSON (i18next) as the format
5. Upload your JSON files
6. Select the i18next version (v3 or v4)
7. AZbox will parse and import all translations

Step 3: Review and Manage

After importing:

• View all translations in a unified interface
• Edit translations with context-aware editor
• Add new languages instantly
• Use machine translation for missing strings
• Collaborate with translators in real-time

Exporting i18next JSON from AZbox

When ready to use translations in your app:

1. Go to Import/Export in your project
2. Select Export and choose JSON (i18next) format
3. Select the i18next version to export
4. Choose target languages
5. Download the generated JSON files
6. Place them in your project’s locales/ directory

Using i18next JSON in Your Application

React with react-i18next

Installation:

npm install i18next react-i18next

Configuration:

import i18n from 'i18next';
import { initReactI18next } from 'react-i18next';
import en from './locales/en/translation.json';
import es from './locales/es/translation.json';

i18n
  .use(initReactI18next)
  .init({
    resources: {
      en: { translation: en },
      es: { translation: es }
    },
    lng: 'en',
    fallbackLng: 'en',
    interpolation: {
      escapeValue: false
    }
  });

export default i18n;

Usage in components:

import { useTranslation } from 'react-i18next';

function Welcome() {
  const { t } = useTranslation();
  
  return (
    <div>
      <h1>{t('welcome')}</h1>
      <p>{t('greeting', { name: 'User' })}</p>
    </div>
  );
}

Vue.js with vue-i18next

import Vue from 'vue';
import i18next from 'i18next';
import VueI18Next from '@panter/vue-i18next';

Vue.use(VueI18Next);

i18next.init({
  lng: 'en',
  resources: {
    en: { translation: require('./locales/en.json') },
    es: { translation: require('./locales/es.json') }
  }
});

const i18n = new VueI18Next(i18next);

new Vue({
  i18n,
  render: h => h(App)
}).$mount('#app');

Node.js

const i18next = require('i18next');

i18next.init({
  lng: 'en',
  resources: {
    en: { translation: require('./locales/en.json') },
    es: { translation: require('./locales/es.json') }
  }
});

console.log(i18next.t('welcome'));
console.log(i18next.t('greeting', { name: 'World' }));

Best Practices for i18next JSON

1. Use Namespaces for Large Projects

locales/en/
├── common.json      (shared UI elements)
├── auth.json        (authentication)
├── dashboard.json   (dashboard features)
├── errors.json      (error messages)
└── validation.json  (form validation)

2. Use Descriptive, Hierarchical Keys

Bad:

{
  "btn1": "Submit",
  "msg": "Error occurred"
}

Good:

{
  "form": {
    "submit": "Submit",
    "cancel": "Cancel"
  },
  "errors": {
    "generic": "An error occurred",
    "network": "Network error"
  }
}

3. Keep Translations Consistent

{
  "actions": {
    "save": "Save",
    "cancel": "Cancel",
    "delete": "Delete",
    "edit": "Edit"
  }
}

4. Handle All Plural Forms

{
  "notification_zero": "No notifications",
  "notification_one": "{{count}} notification",
  "notification_other": "{{count}} notifications"
}

5. Provide Context with Key Names

{
  "button_save_document": "Save Document",
  "button_save_settings": "Save Settings",
  "title_main_dashboard": "Dashboard",
  "title_user_profile": "Your Profile"
}

Common Issues and Solutions

Issue: Plurals Not Working

Problem: Plural forms not displaying correctly.

Solution: Ensure you’re using the correct plural suffix for your i18next version:

• v4: _one, _other, _few, _many, _zero, _two
• v3: _plural

Issue: Interpolation Not Replaced

Problem: {{value}} appears literally in output.

Solution: Check that you’re passing the interpolation values:

// Wrong
t('greeting')

// Correct
t('greeting', { name: 'John' })

Issue: Nested Keys Not Found

Problem: t('nav.home') returns the key instead of value.

Solution: Ensure your JSON structure matches the key path and resources are loaded correctly.

AZbox i18next Features

When you import i18next JSON to AZbox, you get:

• Automatic version detection - AZbox detects v3 or v4 format
• Namespace support - Manage multiple namespaces per project
• Plural form validation - Ensures all plural variants are present
• Interpolation highlighting - Visual markers for {{variables}}
• Nesting support - Handles $t() references correctly
• Context variant management - Easy management of context keys
• Translation memory - Leverage previous translations
• Machine translation - Fill gaps with AI-powered translation
• Over-the-air updates - Update without redeploying

Migrating Between Versions

v3 to v4 Migration

If upgrading from v3 to v4, plural keys need updating:

v3:

{
  "item": "{{count}} item",
  "item_plural": "{{count}} items"
}

v4:

{
  "item_one": "{{count}} item",
  "item_other": "{{count}} items"
}

Use the i18next-v4-format-converter to automate migration.

Conclusion

i18next JSON is the industry standard for JavaScript localization, offering powerful features for handling complex translation scenarios. With AZbox’s full i18next support, you can:

1. Import existing JSON files with all features preserved
2. Support all i18next versions (v1-v4)
3. Manage translations in a collaborative cloud platform
4. Export JSON files ready for use in any i18next project
5. Update translations over-the-air without rebuilding

Ready to streamline your JavaScript localization workflow?

Start Your Free Trial | View Pricing

---

AZbox provides comprehensive support for i18next JSON format, making it the ideal localization platform for JavaScript developers. Import, manage, and export your translations with ease.

References:

• i18next JSON Format Documentation
• i18next Official Website