String Catalog Logo
String Catalog
Start Free Log In
Skip to content
Home
Docs
i18next JSON Parser Reference

Parsers

i18next JSON Parser Reference

Technical reference for how String Catalog parses i18next JSON files, infers locales from paths, preserves namespaces, and writes localized JSON output.

The i18next JSON parser handles React and i18next-style translation files where each locale is represented by one or more JSON files.

Detection Rules

  • File extension: .json
  • Path must identify a supported locale
  • File must contain a JSON object with at least one translation string

String Catalog does not treat every JSON file as localizable. Files such as package.json, app config JSON, or arbitrary data files are ignored or rejected unless they match a supported i18next path shape and look like translation content.

Supported File Patterns

Supported layouts include:

  • locales/<locale>/<namespace>.json
  • translations/<namespace>.<locale>.json
  • <locale>.json

Examples:

  • public/locales/en/common.json
  • public/locales/fr-CA/onboarding.json
  • translations/common.es-419.json
  • en.json

Repository projects discover these files automatically. Custom projects can process i18next JSON through the Custom Pipeline API. Dashboard uploads are limited to .xcstrings today.

Parsing Behavior

  • Locale is inferred from the file path.
  • Namespace is inferred from the file path when the layout provides one.
  • Nested JSON objects are flattened into stable translation keys for tracking.
  • Flat JSON files keep literal dot keys as literal keys.
  • Array values can be tracked and written back in the original JSON structure.

The parser groups locale files that represent the same namespace so one base file and its translated locale files stay connected.

Locale Normalization Behavior

i18next JSON uses BCP-47-style locale matching. Locale codes such as fr-CA, es-419, and zh-Hant-HK are resolved against String Catalog's supported language list.

The base locale comes from the project base language. On a fresh custom project, upload the intended base locale first or choose the base language when creating an API-managed project.

Review State Handling

When a base string changes, existing non-base translations can be marked for review according to your project's Sync & Retranslation settings. Filled translations are preserved unless a trigger asks String Catalog to refresh them.

i18next files do not have Xcode-style source states, so NeedsReview behavior is driven by String Catalog's tracked state and project settings rather than file-native review metadata.

Interpolation, Plurals, and Markup

String Catalog detects common i18next syntax including:

  • Interpolation such as {{name}}
  • Formatted interpolation such as {{value, number}}
  • Nesting such as $t(common.save)
  • Trans-style tags such as <strong> or numeric component tags
  • Plural suffixes such as _one, _many, and _other

Plural groups can produce warnings when a locale is missing expected plural categories.

Rename Handling

i18next JSON parsing is key-driven. It does not rely on Xcode rename metadata, but tracked source values and project settings still help String Catalog decide when existing translations should be preserved or refreshed.

Write-Back Normalization

Generated output preserves the detected JSON structure:

  • Nested files are written as nested JSON.
  • Flat files are written with flat keys.
  • Locale files are written back to the same path layout, using the target locale in the path.
  • JSON is formatted consistently with two-space indentation.

Edge Cases Handled

  • Large JSON translation files are supported during repository discovery.
  • Uppercase .JSON extensions are accepted during repository discovery.
  • Common dependency directories are excluded from repository discovery.
  • Unsupported JSON files are rejected instead of being parsed as app strings.