i18next JSON v4 Migration Guide: Plurals, Context, and Real Production Files

If you are migrating an i18next app to JSON v4, the main risk is not the new plural categories. It is the old production mess already living in your locale files.

For web teams using i18next, the jump to JSON v4 is not just a version change. It is a shift toward more standardized plural behavior and cleaner interoperability with modern localization tooling.

That matters because i18next often becomes the translation backbone of large React, Next.js, and JavaScript applications. Once there are thousands of keys across many locales, small inconsistencies in file conventions become real maintenance problems.

Why teams move to v4

The primary driver behind v4 was the need for a more robust and standardized approach to pluralization.

In older versions, plural suffix patterns were inconsistent across languages. JSON v4 aligns more closely with CLDR (Common Locale Data Repository) categories, which makes plural handling easier for both tooling and humans to reason about.

That CLDR alignment matters because plural categories such as one, few, many, and other are not arbitrary labels. They are part of a widely used linguistic standard that many internationalization systems already understand.

Key Differences in Pluralization

In v4, plural keys now use a standard suffix based on the plural category (zero, one, two, few, many, other) rather than simple incrementing numbers.

The Old Way (v3)

{
  "key_plural": "items",
  "key_0": "item",
  "key_1": "item",
  "key_2": "items"
}

The New Way (v4)

{
  "key_one": "item",
  "key_other": "items"
}

Note: For languages with more complex rules, like Arabic or Polish, you would use keys like key_few or key_many as defined by the CLDR rules.

The practical advantage is not only correctness. It is portability. A CLDR-like naming scheme is easier for translators, localization tools, and engineers to interpret than a format that relies on ad hoc suffixes.

What v4 improves beyond plurals

Moving to the latest format offers several benefits for large-scale localization:

• Standardized Suffixes: No more guessing if you should use _plural or _2.
• Deep Nesting Support: Better organization for large-scale translation files.
• Improved Interpolation: Seamlessly inject variables into your strings using {{val}} syntax.
• Natural Context: Use the _context suffix to provide variations of the same string (e.g., friend_male vs. friend_female).

Why CLDR Alignment Is Such a Big Deal

Many teams underestimate how much friction plural naming creates until they localize into languages with more than two plural forms.

JSON v4 helps because it maps more naturally to the way localization professionals already think about plural categories. That improves:

• compatibility with translation management systems
• readability for engineers reviewing locale files
• migration paths across tools and frameworks
• correctness in languages that do not follow a simple singular/plural split

If your app needs even richer message logic, it is worth comparing i18next JSON v4 with ICU MessageFormat, which solves a related problem with a different syntax model.

Implementation Example

To use JSON v4 in your project, ensure your i18next initialization specifies the compatibility version:

i18next.init({
  compatibilityJSON: 'v4',
  lng: 'en',
  resources: {
    en: {
      translation: {
        "key_one": "You have {{count}} message.",
        "key_other": "You have {{count}} messages."
      }
    }
  }
});

i18next JSON v4 vs. Other Formats

i18next JSON v4 is a strong fit for modern JavaScript applications, but it is not the only viable format.

Compared with nearby alternatives:

• YAML may feel more readable to some teams but is less standard in the i18next ecosystem
• Fluent offers a more expressive model for asymmetric localization and author-friendly messages
• ICU is more explicit for complex linguistic logic, especially when shared across multiple platforms

The right choice depends on the stack. For teams already committed to i18next, JSON v4 is usually the cleanest path because it matches the framework’s expected conventions.

Migration Considerations 🧪

Upgrading to v4 is conceptually simple, but production apps should still approach it carefully.

Audit plural keys first

Older projects may carry inconsistent suffixes or custom conventions. Those need to be mapped deliberately before the upgrade is considered complete.

Validate interpolation and context handling

Plural migration is not the only risk. Teams should also confirm that interpolation tokens and contextual variations still behave as expected.

Test real locale files, not only examples

Many migration guides use short demo resources. Real projects usually contain deep nesting, reused key prefixes, and years of historical inconsistencies.

Validate v4 locally before rollout

One of the easiest ways to de-risk a v4 migration is to test representative locale files locally before changing the whole application over.

That lets teams catch plural mismatches, broken nesting assumptions, and awkward copy before the new format lands in production. It is also where MetalGlot fits well: as a private workspace for iterating on real locale files rather than only demo examples.

Next steps

Upgrading your existing translation files to v4 is a significant step toward a more maintainable codebase. Check out the i18next Documentation for a full migration guide and a deep dive into language-specific plural rules.

Where MetalGlot fits the i18next workflow

Modern web apps often have thousands of keys in their i18next JSON files. Managing these across dozens of languages is the biggest bottleneck in the development lifecycle.

MetalGlot works with JSON v4 as a structured localization format, not as a generic JSON blob.

• v4-aware processing: Preserve the relationship between plural and context variants.
• Deep JSON support: Keep nested file structure intact.
• Private local workflows: Translate modern app copy without sending it to third-party APIs.

Final take

i18next JSON v4 is a meaningful improvement because it turns one of the messiest parts of localization, plural naming, into something more standardized and interoperable.

For JavaScript teams already using i18next, it is usually the right long-term format. The main work is not deciding whether v4 is better. It is migrating carefully enough that real production locale files stay correct.