JSON Localization File Structure

JSON (JavaScript Object Notation) has become the de facto standard for localization files due to its simplicity, readability, and universal support across programming languages.

1. Basic Structure

A typical JSON localization file follows a nested object structure that organizes translations logically:

{
  "welcome": {
    "greeting": "Welcome to our application!",
    "subtitle": "Start your journey today"
  },
  "navigation": {
    "home": "Home",
    "about": "About",
    "contact": "Contact",
    "settings": "Settings"
  },
  "buttons": {
    "save": "Save",
    "cancel": "Cancel",
    "delete": "Delete",
    "edit": "Edit"
  }
}

2. Advanced Structure Patterns

Hierarchical Organization

For larger applications, organize translations in a hierarchical structure that mirrors your application's architecture:

{
  "dashboard": {
    "sidebar": {
      "navigation": {
        "items": {
          "overview": "Overview",
          "analytics": "Analytics",
          "reports": "Reports"
        }
      },
      "user": {
        "profile": {
          "name": "Name",
          "email": "Email",
          "role": "Role"
        }
      }
    }
  }
}

Parameterized Messages

Use placeholders for dynamic content to create flexible translation strings:

{
  "messages": {
    "welcome_user": "Welcome back, {{name}}!",
    "items_count": "You have {{count}} items in your cart",
    "percentage_complete": "{{percentage}}% complete"
  }
}

3. Naming Conventions

Key Naming Styles

Choose a consistent naming convention across your project:

• camelCase: welcomeMessage
• snake_case: welcome_message
• kebab-case: welcome-message (not recommended for JSON keys)

Descriptive Key Names

Use descriptive, hierarchical naming for better organization:

4. Best Practices

Consistency Across Languages

Ensure all language files follow the same structure and conventions:

• Use consistent naming conventions across all languages
• Maintain identical JSON structure in all language files
• Keep key names in English for better maintainability
• Ensure all required keys exist in every language file

Performance Optimization

Optimize translation files for better loading performance:

• Keep individual files under 100KB for optimal loading
• Use code splitting and lazy loading for large applications
• Implement intelligent caching strategies
• Consider tree-shaking unused translations in production

Error Handling and Fallbacks

Implement robust error handling for missing translations:

• Always provide fallback values for missing translations
• Handle translation loading failures gracefully
• Log missing translations in development mode
• Display user-friendly error messages for failed loads

5. Advanced Techniques

Context-Aware Translations

Provide different translations based on context to ensure accuracy:

{
  "button": {
    "save": "Save",
    "save_context": {
      "document": "Save Document",
      "settings": "Save Settings",
      "profile": "Save Profile"
    }
  }
}

Pluralization Support

Handle different plural forms correctly for each language:

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

Gender-Specific Translations

Support gender-specific translations where grammatically required:

{
  "welcome": {
    "male": "Welcome, Mr. {{name}}",
    "female": "Welcome, Ms. {{name}}",
    "other": "Welcome, {{name}}"
  }
}

6. Validation and Quality Assurance

JSON Schema Validation

Use JSON Schema to enforce structure and ensure consistency across all language files:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "welcome": {
      "type": "object",
      "properties": {
        "greeting": { "type": "string" },
        "subtitle": { "type": "string" }
      },
      "required": ["greeting", "subtitle"]
    }
  },
  "required": ["welcome", "navigation", "buttons"]
}

Automated Testing and Validation

Implement comprehensive automated checks to maintain quality:

• JSON syntax validity - Ensure all files are valid JSON
• Missing translation keys - Verify all required keys exist
• Inconsistent parameter usage - Check for mismatched placeholders
• Translation completeness - Ensure no empty or missing values
• Schema compliance - Validate against defined JSON Schema

For more information on JSON localization standards, visit the W3C Internationalization Best Practices.