Multi-Language Support in JSON Documentation

In today's global development landscape, providing documentation in multiple languages is crucial for reaching a wider audience and ensuring clarity for developers worldwide. While traditional documentation formats often rely on dedicated localization workflows, storing documentation content within structured data like JSON offers interesting possibilities for managing translations. This article explores different approaches for implementing multi-language support when your documentation content is primarily stored in JSON format.

Why JSON for Documentation?

JSON (JavaScript Object Notation) is a lightweight data-interchange format that is easy for humans to read and write and easy for machines to parse and generate. Using JSON for documentation can be beneficial for:

• Automation: Easily parse and process documentation content programmatically.
• Consistency: Enforce a consistent structure for different documentation sections or components.
• Integration: Integrate documentation content directly into applications, tools, or APIs.
• Version Control: Manage documentation changes alongside code in standard version control systems.

However, JSON itself doesn't have built-in features for localization. We need to design a structure within the JSON to accommodate multiple languages.

Approach 1: Separate JSON Files per Language

This is perhaps the most straightforward approach. You maintain completely separate JSON files for each supported language. Each file follows the same structure but contains content translated into the respective language.

File Structure Example:

docs/
├── en/
│   └── api_errors.json
├── es/
│   └── api_errors.json
└── fr/
    └── api_errors.json

JSON File Example (en/api_errors.json):

{
  "title": "API Error Codes",
  "description": "Detailed explanation of common API error codes.",
  "errors": [
    {
      "code": 400,
      "name": "Bad Request",
      "message": "The request was malformed or invalid."
    },
    {
      "code": 401,
      "name": "Unauthorized",
      "message": "Authentication is required and has failed or has not yet been provided."
    }
  ]
}

JSON File Example (es/api_errors.json):

{
  "title": "Códigos de Error de la API",
  "description": "Explicación detallada de los códigos de error comunes de la API.",
  "errors": [
    {
      "code": 400,
      "name": "Solicitud Incorrecta",
      "message": "La solicitud estaba mal formada o no era válida."
    },
    {
      "code": 401,
      "name": "No Autorizado",
      "message": "Se requiere autenticación y ha fallado o aún no se ha proporcionado."
    }
  ]
}

Advantages

• Simplicity: Each file is self-contained and easy to manage for translators.
• Clear Separation: Content and its translations are completely separate.
• Loading Efficiency: You only load the data needed for the active language.

Disadvantages

• Synchronization: Keeping the structure of files consistent across all languages can be challenging as documentation evolves.
• Redundancy: Non-translatable data (like error codes) is duplicated in every file.
• Discovery: Harder to see all translations for a single piece of content side-by-side.

Approach 2: Single JSON File with Language Keys

In this approach, you keep all language versions of a piece of content within a single JSON file or structure, typically nested under language keys (e.g., "en", "es", "fr").

This can be done at different levels:

Option A: Language Keys per Translatable String

Wrap each individual translatable string value in an object that contains language keys.

{
  "title": {
    "en": "API Error Codes",
    "es": "Códigos de Error de la API",
    "fr": "Codes d'Erreur API"
  },
  "description": {
    "en": "Detailed explanation of common API error codes.",
    "es": "Explicación detallada de los códigos de error comunes de la API.",
    "fr": "Explication détaillée des codes d'erreur API courants."
  },
  "errors": [
    {
      "code": 400,
      "name": {
        "en": "Bad Request",
        "es": "Solicitud Incorrecta",
        "fr": "Mauvaise Requête"
      },
      "message": {
        "en": "The request was malformed or invalid.",
        "es": "La solicitud estaba mal formada o no era válida.",
        "fr": "La requête était mal formée ou invalide."
      }
    }
    // ... more errors
  ]
}

Option B: Language Keys Grouping Top-Level Content

Group the entire structure of the document under a top-level language key.

{
  "en": {
    "title": "API Error Codes",
    "description": "Detailed explanation of common API error codes.",
    "errors": [
      {
        "code": 400,
        "name": "Bad Request",
        "message": "The request was malformed or invalid."
      }
      // ... more errors
    ]
  },
  "es": {
    "title": "Códigos de Error de la API",
    "description": "Explicación detallada de los códigos de error comunes de la API.",
    "errors": [
      {
        "code": 400,
        "name": "Solicitud Incorrecta",
        "message": "La solicitud estaba mal formada o no era válida."
      }
      // ... more errors
    ]
  }
  // ... other languages
}

Option B is often cleaner as it keeps the core document structure consistent at the top level, only branching for languages.

Advantages

• Centralized: All language content for a specific document is in one place, easier for translators using tools.
• Structure Consistency: The base structure is maintained across languages.
• Reduced Redundancy (Option B): Non-translatable keys/values (like error codes) can potentially exist once outside language keys if the structure allows, or are simply part of the repeated structure.

Disadvantages

• File Size: The JSON files can become very large as more languages are added.
• Loading Overhead: You load data for *all* languages even if only one is needed (though parsing can be optimized).
• Complexity (Option A): Deeply nested structures with language keys on every string can be verbose.

Implementation Considerations

Regardless of the JSON structure you choose, you'll need logic to handle language selection and data retrieval.

• Loading Data:
  • For separate files: Load the specific JSON file corresponding to the active locale (e.g., /docs/en/api_errors.json).
  • For single files with language keys: Load the single JSON file and then access the data under the key matching the active locale (e.g., data['en']).
• Locale Detection: Determine the user's preferred language from browser settings, URL parameters, user profile, etc.
• Fallback Language: Define a default language (e.g., "en") to use if the user's preferred language is not available.
• Data Access: Your application code will need to retrieve values based on the active language. For Option A (language keys per string), this might involve a helper function like getText(key, locale) that looks up data[key][locale] with a fallback. For Option B (top-level language keys), you'd first select the language block data[locale] and then access keys within that block.

Choosing the Right Approach

The best approach depends on your specific needs and scale:

• Separate Files: Suitable for smaller projects, when content types vary significantly between "documents", or when translation workflows are file-based. Offers good performance for loading only necessary data.
• Single File (Option B): Good for larger projects with many similar documents/components, where centralized translation is preferred, and where the size of the combined file is manageable. Simplifies structure management.
• Single File (Option A): Can work for simple, flat structures like configuration files, but quickly becomes cumbersome for complex, nested documentation structures.

Consider using standard ISO 639-1 locale codes (like "en", "es", "fr", "de") as your language keys or directory names for consistency and compatibility with i18n tools.

Conclusion

Managing multi-language documentation within JSON requires careful consideration of your data structure. Both maintaining separate files per language and consolidating into a single file with language keys are viable strategies, each with its own set of trade-offs regarding manageability, synchronization, and performance. By choosing an approach that aligns with your project's size, complexity, and translation workflow, you can effectively leverage the benefits of JSON for structured documentation while serving a global audience.