Best Way to Handle Localization For Exception Messages in Spring Boot

As applications grow to serve a global audience, localization becomes a crucial aspect of software development. Localization allows applications to adapt to different languages and regions, providing a user-friendly experience.

In this article, I am going to share my favorite way of handling localized exceptions in a Spring Boot application.

Why We Need Localization for Exception Messages?

Localization of exception messages in the backend side is essential for creating a seamless user experience, especially in applications targeting a global audience.

By localizing these messages on the backend and sending them directly to the frontend, we can take the responsibility of managing multiple languages out of frontend developers' shoulders. This approach ensures that the error messages are consistent across all platforms and languages, allowing frontend developers to focus on displaying these messages in a user-friendly manner, such as in an error toast.

As a result, there's no need for the frontend to handle custom exception messages for each language, reducing duplication of effort and the potential for errors, and ensuring that all users receive clear and relevant feedback in their preferred language.

How to Achieve our Goal in Backend Conveniently?

Follow the steps below to attain our goal.

General Exception Class

Start by creating a class that extends from RuntimeException and name it ResponseException. This custom exception will allow you to handle application-specific errors in a more controlled manner.

public class ResponseException extends RuntimeException {

}

Response Error Class

Create a separate class that will be returned in the response when an exception occurs. This class can contain fields like message, timestamp, errorCode, and any other relevant information that you'd like to pass to the frontend.

public record ErrorResponse(int status, String message) {

}

Global Exception Handler

Implement a GlobalExceptionHandler using Spring's @ControllerAdvice annotation. In this class, you can catch the ResponseException and map it to the appropriate localized message based on the user's locale.

@Slf4j
@RestControllerAdvice
@RequiredArgsConstructor
public class GlobalExceptionHandler extends ResponseEntityExceptionHandler {

  @ExceptionHandler(value = ResponseException.class)
  public ResponseEntity<ErrorResponse> handleResponseStatusException(
      ResponseException ex
  ) {
    log.error("ResponseException: {}", ex.getMessage());

    String message = ex.getMessage();

    var errorResponse = new ErrorResponse(ex.getStatus().value(), message);

    return new ResponseEntity<>(errorResponse, ex.getStatus());
  }
}

Language Specific Property Files

To manage the localized messages, create property files for each supported language, such as messages_en.properties for English, messages_az.properties for Azerbaijani, and so on. These files will contain the key-value pairs for each exception message, allowing Spring to automatically resolve the correct message based on the user's locale.

Create those property files in src/main/resources folder.

err.username_already_exists.msg=User with username: {0} is already exists.

Implement Localization Part

I've created bare minimum for handling exceptions in Spring Boot. I assume you are already familiar with above. Let's continue to add translation part.

Modify ResponseException class:

public class ResponseException extends RuntimeException {
  private final String messageTemplate;
  private final transient Object[] params;
  private final Locale locale;

  public static ResponseException notFound(String messageTemplate, Locale locale) {
    return new ResponseException(HttpStatus.NOT_FOUND, messageTemplate, null, locale);
  }

  public static ResponseException notFound(String messageTemplate, Object[] params, Locale locale) {
    return new ResponseException(HttpStatus.NOT_FOUND, messageTemplate, params, locale);
  }

  public static ResponseException forbidden(String messageTemplate, Locale locale) {
    return new ResponseException(HttpStatus.FORBIDDEN, messageTemplate, null, locale);
  }

  public static ResponseException forbidden(String messageTemplate, Object[] params, Locale locale) {
    return new ResponseException(HttpStatus.FORBIDDEN, messageTemplate, params, locale);
  }  
}

Create helper methods for frequently used HttpStatus codes such as NOT_FOUND, FORBIDDEN.

You can use these helper methods in following way:

// some code parts omitted ...
userService.findByUsername(username)
  .orElseThrow(() -> ResponseException.notFound("user_not_found", locale))

Create user_not_found message template in all of your property files.

// file: messages_en.properties
user_not_found=User not found

// file: messages_az.properties
user_not_found=İsdifadəçi tapılmadı

In order to automatically, replace these before returning to the frontend, update method in the GlobalExceptionHandler class.

@Slf4j
@RestControllerAdvice
@RequiredArgsConstructor
public class GlobalExceptionHandler extends ResponseEntityExceptionHandler {

  private final MessageSource messageSource;

  @ExceptionHandler(value = ResponseException.class)
  public ResponseEntity<ErrorResponse> handleResponseStatusException(
      ResponseException ex
  ) {
    log.error("ResponseException: {}", ex.getMessage());

    String message = ex.getMessage();

    String messageTemplate = ex.getMessageTemplate();
    if (StringUtils.isNotBlank(messageTemplate)) {
      message = messageSource.getMessage(messageTemplate, ex.getParams(), ex.getLocale());
    }

    var errorResponse = new ErrorResponse(ex.getStatus().value(), message);

    return new ResponseEntity<>(errorResponse, ex.getStatus());
  }
}

How to Use Dynamic Values in Exception Messages

This way of handling exceptions are useful especially you have to set dynamic values for your exception messages. For instance,

// file: messages_en.properties
err.invalid_phone_number.msg=The phone: {0} is invalid

In order to replace {0} with dynamic value.

public static ResponseException badRequest(
      String messageTemplate, 
      Locale locale,
      String... params
) {
  return new ResponseException(
        HttpStatus.BAD_REQUEST, 
        messageTemplate, 
        params, 
        locale
  );
}

I've put the varargs parameter at the end to pass multiple dynamic parameters without creating new method each time.

I have a dedicated article about Messages with Dynamic values.

Where to Get User's Locale?

I have two approaches to get locales:

Users' locales that are stored on the database based on UI preferences.
Some controller methods accepts optional lang request parameter. This might be useful for testing when frontend developers wants to see how UI will be in different languages. Because sentence length in each language are not same.