i18n Key Naming for Buttons and Form Labels

Naming i18n Keys for Buttons and Labels

Buttons and form labels are the most frequently translated UI elements. Consistent key naming for these elements reduces confusion for translators and makes the codebase easier to maintain.

Button Key Patterns

The most common pattern groups all buttons under a shared namespace:

{
  "common": {
    "buttons": {
      "submit": "Submit",
      "cancel": "Cancel",
      "save": "Save",
      "delete": "Delete",
      "edit": "Edit",
      "close": "Close",
      "confirm": "Confirm",
      "back": "Back",
      "next": "Next",
      "retry": "Retry"
    }
  }
}

For context-specific buttons, include the context in the key:

{
  "checkout": {
    "buttons": {
      "place_order": "Place Order",
      "apply_coupon": "Apply Coupon",
      "update_quantity": "Update"
    }
  }
}

Form Label Patterns

Form labels follow a similar structure, grouped by form or feature:

{
  "forms": {
    "labels": {
      "email": "Email Address",
      "password": "Password",
      "confirm_password": "Confirm Password",
      "first_name": "First Name",
      "last_name": "Last Name",
      "phone": "Phone Number"
    },
    "placeholders": {
      "email": "you@example.com",
      "password": "Enter your password",
      "search": "Search..."
    }
  }
}

Separation of Concerns

Keep these as separate key groups:

1. Labels -- the visible text next to or above a form field
2. Placeholders -- the hint text inside the field
3. Help text -- additional guidance below the field
4. Validation messages -- error text when validation fails
5. Aria labels -- accessibility text not visible on screen

{
  "fields": {
    "email": {
      "label": "Email Address",
      "placeholder": "you@example.com",
      "help": "We will never share your email.",
      "errors": {
        "required": "Email is required.",
        "invalid": "Please enter a valid email address."
      },
      "aria_label": "Enter your email address"
    }
  }
}

Avoid Generic Keys

Avoid keys like button1, label_a, or text_23. These provide no context to translators and make code reviews difficult. Always use descriptive names that reflect the content or purpose.