i18n Key Naming for Error Messages and Validation

Naming i18n Keys for Error Messages

Error messages require careful key naming because they often contain dynamic values (field names, limits, counts) and must be clear to both developers and translators.

Error Key Structure

A recommended structure separates errors by category:

{
  "errors": {
    "validation": {
      "required": "{{field}} is required.",
      "min_length": "{{field}} must be at least {{min}} characters.",
      "max_length": "{{field}} cannot exceed {{max}} characters.",
      "email_format": "Please enter a valid email address.",
      "password_mismatch": "Passwords do not match.",
      "number_range": "{{field}} must be between {{min}} and {{max}}."
    },
    "api": {
      "network_error": "Unable to connect. Please check your internet connection.",
      "server_error": "Something went wrong. Please try again later.",
      "timeout": "The request timed out. Please try again.",
      "not_found": "The requested resource was not found.",
      "unauthorized": "Your session has expired. Please log in again.",
      "forbidden": "You do not have permission to perform this action.",
      "rate_limited": "Too many requests. Please wait {{seconds}} seconds."
    },
    "file": {
      "too_large": "File size exceeds the {{limit}} limit.",
      "invalid_type": "Only {{types}} files are accepted.",
      "upload_failed": "File upload failed. Please try again."
    }
  }
}

Dynamic Interpolation

Most i18n libraries support interpolation placeholders:

• react-i18next: {{variable}}
• vue-i18n: {variable} or @:key for linked messages
• next-intl: {variable}
• Rails I18n: %{variable}
• Django gettext: %(variable)s

Include the interpolation syntax in your key values so translators know which parts are dynamic and must not be translated.

Error Code Mapping

For API errors, consider mapping HTTP status codes or custom error codes to keys:

{
  "errors": {
    "codes": {
      "E001": "Invalid credentials. Please check your email and password.",
      "E002": "Account is locked. Contact support for assistance.",
      "E003": "Email address is already registered."
    }
  }
}

User-Friendly Error Messages

Translation keys for errors should produce messages that:

1. Explain what happened -- not just "Error" but what specifically failed
2. Suggest a fix -- tell the user what to do next
3. Avoid technical jargon -- "network error" is better than "ECONNREFUSED"
4. Are grammatically complete -- translators need full sentences for correct grammar in all languages