
## Table of contents

## Introduction

In this article, we will learn how to use formatting instances to format dates and numbers.
We will take a look at the `java.text` package and its classes. We will also learn how to use the `java.time` package to work with dates and times.
Finally, we will learn how to use the `ResourceBundle` object to retrieve localized messages from a properties file.

## `Locale` class changes

Since Java 19, **all constructors of the `Locale` class have been deprecated**.
Instead, you should use the `Locale.of` static constructors to create a new `Locale` instance
or use the `Locale.Builder` class to create a new `Locale` instance.

```java
// static constructors
Locale.of(language);
Locale.of(language, country);
Locale.of(language, country, variant);

// builder
new Locale.Builder()
    .setLanguage(language)
    .setRegion(country)
    .setVariant(variant)
    .build();

// deprecated constructors
new Locale(language);
new Locale(language, country);
new Locale(language, country, variant);
```


## Number formatting

The `NumberFormat` class offers a number of methods for returning different instances for formatting numbers.

 - `getPercentInstance(Locale)` - formats numbers as percentages.
 - `getCurrencyInstance(Locale)` - formats numbers as currency values.
 - `getIntegerInstance(Locale)` - formats numbers as integers.
 - `getNumberInstance(Locale)` - formats numbers as general-purpose numbers.
 - `getCompactNumberInstance(Locale, NumberFormat.Style)` - formats numbers as compact numbers.

### Percentages formatting

Different countries use different symbols for percentages. For example, in the US, the percentage symbol is `%`, while in the UK, it is `£`.

```java
NumberFormat.getPercentInstance(Locale.US).format(0.75);
// 75%

NumberFormat.getPercentInstance(LOCALE_FRANCE).format(0.75);
// 75 %

NumberFormat.getPercentInstance(Locale.of("ar", "SA")).format(0.75);
// ٪٧٥
```

### Long numbers formatting

Compact numbers are a method of formatting numbers in a more compact way. For example, instead of writing `1,000,000`
you can write `1M`.
They are useful when you want to display a large number in a small space. Every locale has its own set of compact
numbers. There are 4 different styles of compact numbers:

 - `NumberFormat.Style.SHORT` - the shortest form of the compact number. For example, `1M` for `1,000,000`.
 - `NumberFormat.Style.LONG` - the longest form of the compact number. For example, `1 million` for `1,000,000`.


```java
// NumberFormat.Style.SHORT

NumberFormat.getCompactNumberInstance(LOCALE_US, Style.SHORT).format(1_213_700);
// 1M

NumberFormat.getCompactNumberInstance(LOCALE_FRANCE, Style.SHORT).format(1_213_700);
// 1 M

NumberFormat.getCompactNumberInstance(LOCALE_POLAND, Style.SHORT).format(1_213_700);
// 1 mln


// NumberFormat.Style.LONG

NumberFormat.getCompactNumberInstance(LOCALE_US, Style.LONG).format(12_137);
// 12 thousand

NumberFormat.getCompactNumberInstance(LOCALE_FRANCE, Style.LONG).format(12_137);
// 12 mille

NumberFormat.getCompactNumberInstance(LOCALE_POLAND, Style.LONG).format(12_137);
// 12 tysięcy
```

### Numbers formatting

The `NumberFormat` class provides a number of methods for formatting numbers.

```java
NumberFormat.getNumberInstance(localeUs).format(1234567.89);
// 1,234,567.89

NumberFormat.getNumberInstance(localeFrance).format(1234567.89);
// 1 234 567,89

NumberFormat.getNumberInstance(localePoland).format(1234567.89);
// 1 234 567,89
```


### Money formatting

Currency formatting is useful when you want to display a number as a currency value. For example, instead of joining
currency symbol and number you can use the `NumberFormat` instance which does it for you in the best possible way,
taking into account the locale.

```java
NumberFormat.getCurrencyInstance(localePoland).format(123.45);
// 123,45 zł

NumberFormat.getCurrencyInstance(localeFrance).format(123.45);
// 123,45 €

NumberFormat.getCurrencyInstance(localeUS).format(123.45);
// $123.45
```

Note that different locales use different symbols for decimal separators and grouping separators. For example, in the US, the decimal separator is `.`, while in Poland and France, it is `,`.

## Symbols and currencies

`NumberFormat` are powerful tool, but what if you want to display a currency symbol or a decimal separator? You can use the `DecimalFormatSymbols` class to get the symbols for a given locale.

```java
Currency currency = DecimalFormatSymbols.getInstance(localePoland).getCurrency();
currency.getDisplayName(LOCALE_POLAND);
// złoty polski

currency.getDisplayName(Locale.FRANCE);
// zloty polonais

currency.getDisplayName(Locale.US);
// Polish zloty
```

Note that we took Polish currency (złoty polski) and `Locale.FRANCE` and Java returned the French name of the currency (zloty polonais).
If we took `Locale.US` and Polish currency, Java returned the English name of the currency (Polish zloty).

Returning symbols works in the same way:
```java
currency.getSymbol(LOCALE_POLAND);
// zł

currency.getSymbol(Locale.FRANCE);
// PLN

currency.getSymbol(Locale.US);
// PLN
```

The `DecimalFormatSymbols` class provides a set of symbols (such as the currency symbol) that are used to format numbers.


```java
DecimalFormatSymbols.getInstance(LOCALE_POLAND).getCurrencySymbol();
// zł

DecimalFormatSymbols.getInstance(Locale.FRANCE).getCurrencySymbol();
// €

DecimalFormatSymbols.getInstance(LOCALE_POLAND).getGroupingSeparator();
// ' '

DecimalFormatSymbols.getInstance(Locale.US).getGroupingSeparator();
// ,
```

## Date formatting

After previous sections, you should be familiar with formatting values using `getXXXInstance` methods and `Locale`
objects. You shouldn't be surprised if I tell you that dates formatting works the same way!

The `DateFormat` class provides a number of methods for formatting date and time.

 - `getDateTimeInstance(int dateStyle, int timeStyle, Locale locale)` - returns a `DateFormat` instance that formats dates and times.
 - `getDateInstance(int dateStyle, Locale locale)` - returns a `DateFormat` instance that formats dates.
 - `getTimeInstance(int timeStyle, Locale locale)` - returns a `DateFormat` instance that formats times.

All methods need a style of date or time and locale. The `DateFormat` class provides a number of constants for formatting dates and times, there are 4 main styles:

 - `DateFormat.SHORT` - the shortest form of the date or time.
 - `DateFormat.MEDIUM` - the medium form of the date or time.
 - `DateFormat.LONG` - the longest form of the date or time.
 - `DateFormat.FULL` - the full form of the date or time.

```java
Date wonderfulDay = Date.from(LocalDateTime.of(2005, 4, 2, 21, 37).toInstant(UTC));

DateFormat.getDateTimeInstance(DateFormat.FULL, DateFormat.FULL, LOCALE_POLAND).format(wonderfulDay)
// sobota, 2 kwietnia 2005 23:37:00 czas środkowoeuropejski letni

DateFormat.getDateTimeInstance(DateFormat.FULL, DateFormat.FULL, LOCALE_FRANCE).format(wonderfulDay)
// samedi 2 avril 2005 à 23:37:00 heure d’été d’Europe centrale

DateFormat.getDateTimeInstance(DateFormat.FULL, DateFormat.FULL, LOCALE_US).format(wonderfulDay)
// Saturday, April 2, 2005 at 11:37:00 PM Central European Summer Time
```

Time has been automatically converted to the local time zone in the first line, where we passed local time and converted it into the UTC time zone.

## Getting messages from resource bundles

In the previous sections, we learned how to format values using `Locale` objects. In this section, we will learn how to read translated messages from the `ResourceBundle` class.

The `ResourceBundle` class is a collection of key-value pairs. The keys are strings and the values are objects. The `ResourceBundle` class provides a number of methods for getting values from the bundle.

 - `getString(String key)` - returns a string for the given key.
 - `getObject(String key)` - returns an object for the given key.
 - `getKeys()` - returns an `Enumeration` of the keys contained in this `ResourceBundle` and its parent bundles.

Put the following code in the `src/main/resources/messages_pl_PL.properties` file.

```properties
footerText=© 2023 SimpleLocalize. Wszelkie prawa zastrzeżone.
linkText=Utwórz konto SimpleLocalize
message=Dziękujemy za wypróbowanie naszego demo SimpleLocalize dla Javy!
title=Hej {0}!
```

Now, we can read the messages using `ResourceBundle` object.

```java
ResourceBundle bundle = ResourceBundle.getBundle("messages", LOCALE_POLAND);

bundle.getString("linkText");
// Utwórz konto SimpleLocalize

bundle.getString("title");
// Hej {0}!
```

As you can see, the `title` message contains a placeholder `{0}`. We can use the `MessageFormat` class to replace the placeholder with a value.

```java
ResourceBundle bundle = ResourceBundle.getBundle("messages", LOCALE_POLAND);
String title = bundle.getString("title");
String message = MessageFormat.format(title, "Jakub");
// Hej Jakub!
```

One of the advantages of using `ResourceBundle` instead just reading from text files is that it supports inheritance.
You can create a bundle that extends another bundle. In this case, the `ResourceBundle` class will look for the key in the current bundle and if it doesn't find it, it will look for it in the parent bundle.


## String normalization

Normalization is the process of converting a string to a normalized form. The `java.text.Normalizer` class provides a number of methods for normalizing strings.

The `Normalizer.Form` class provides a number of constants for normalization forms.

- `Normalizer.Form.NFC` - Canonical decomposition, followed by canonical composition.
- `Normalizer.Form.NFD` - Canonical decomposition.
- `Normalizer.Form.NFKC` - Compatibility decomposition, followed by canonical composition.
- `Normalizer.Form.NFKD` - Compatibility decomposition.

### What is canonical and compatibility decomposition?

In simple words, not technical and unprofessional words, it means that the string with diacritics will be _converted_ to the string without diacritics.
Normalizer splits the string into a sequence of characters and then combines them into a new string without diacritics.

```java
Normalizer
  .normalize("Tĥïŝ ĩš â fůňķŷ Šťŕĭńġ", Normalizer.Form.NFD)
  .replaceAll("[^\\p{ASCII}]", "")
//This is a funky String
```

When else might it be useful? When you work with strings that contain special characters, you should normalize them
before comparing them. Or you want to normalize half-width to full-width characters. Half-width characters are common in
Japanese and Chinese languages, and they were used before the computer era.

```java
Normalizer.normalize("Ｈｅｌｌｏ，　ｗｏｒｌｄ！", Normalizer.Form.NFKC);
// Hello, world!
```

## Summary

In this article, we didn't cover every problem when it comes to internationalization and localization, but we learned
how to face the most common challenges in international Java projects.
We learned how to use the `Locale` class and saw what news Java 19 brings and what it deprecates. We learned how to get
messages from resource bundles, normalize strings and format dates and numbers.

## Resources

- [Java 19: List of supported locales](https://www.oracle.com/java/technologies/javase/jdk19-suported-locales.html)
- [Java 19: Locale class](https://docs.oracle.com/en/java/javase/19/docs/api/java.base/java/util/Locale.html)
- [Java 19: NumberFormat class](https://docs.oracle.com/en/java/javase/19/docs/api/java.base/java/text/NumberFormat.html)
- [Java 19: DecimalFormatSymbols class](https://docs.oracle.com/en/java/javase/19/docs/api/java.base/java/text/DecimalFormatSymbols.html)
- [Java 19: Currency class](https://docs.oracle.com/en/java/javase/19/docs/api/java.base/java/util/Currency.html)
- [Java 19: Locale.Builder](https://docs.oracle.com/en/java/javase/19/docs/api/java.base/java/util/Locale.Builder.html)
- [Billy Korando: Internationalization in Java - Sip of Java](https://inside.java/2022/08/17/sip064/)
- [Java 19: ResourceBundle class](https://docs.oracle.com/en/java/javase/19/docs/api/java.base/java/util/ResourceBundle.html)
- [Half-width kana](https://en.wikipedia.org/wiki/Half-width_kana)
- [Java 19: Normalizer class](https://docs.oracle.com/en/java/javase/19/docs/api/java.base/java/text/Normalizer.html)
- [Sean Patrick Floyd: Normalization example](https://stackoverflow.com/a/4122207/1133169)


Java 19: Internationalization


## Table of contents

This tutorial comes with GitHub repository with the final code. You can clone it and follow along.
[https://github.com/simplelocalize/spring-boot-i18n](https://github.com/simplelocalize/spring-boot-i18n)

## Introduction

Internationalization (i18n) is the process of designing your application to be adapted to various languages, regional
peculiarities, and technical requirements of a target market.
Internationalization is a crucial step in the process of localizing your product. In this tutorial, we will show you how
to use Spring Boot to create a simple internationalized application,
how to get translated messages from `messages_xx.properties` files, render translated HTML from HTML template
using [Thymeleaf](https://www.thymeleaf.org) and how to use `LocaleResolver` to change the language of the application.

## Used technologies

- Java 19
- Spring Boot 3.0 (RC)
- Thymeleaf 3
- Maven
- SimpleLocalize Editor

![translated spring boot page](/blog/spring-boot/translated-springboot-webpages.png)

## Configuration

### 1. Create `messages_xx.properties` files

The messages are stored in the `messages_XX.properties` files. The `XX` is the language code. For
example, `messages_pl_PL.properties` is the Polish version of the messages.

```properties
footerText=© 2023 SimpleLocalize. Wszelkie prawa zastrzeżone.
linkText=Utwórz konto SimpleLocalize
message=Dziękujemy za wypróbowanie naszego demo SimpleLocalize dla Spring Boot!
title=Hej {0}!
```

If you are using SimpleLocalize, you can download the `messages_XX.properties` files providing your `apiKey`
in `simplelocalize.yml` file and invoking `simplelocalize download` command.

![Downloading messages_xx.properties files via SimpleLocalize CLI](/blog/spring-boot/java-properties-download.mp4)

### 2. Configure `messages_xx.properties` location

The default location for messages is `src/main/resources/messages`.
You can change this by setting the `spring.messages.basename` property in your `application.properties` file
or by providing your `ResourceBundleMessageSource` bean.

```java
@Bean
public ResourceBundleMessageSource messageSource() {
    var resourceBundleMessageSource=new ResourceBundleMessageSource();
    resourceBundleMessageSource.setBasenames("i18n/messages"); // directory with messages_XX.properties
    resourceBundleMessageSource.setUseCodeAsDefaultMessage(true);
    resourceBundleMessageSource.setDefaultLocale(Locale.of("en"));
    resourceBundleMessageSource.setDefaultEncoding("UTF-8");
    resourceBundleMessageSource.setAlwaysUseMessageFormat(true);
    return resourceBundleMessageSource;
}
```

![messages_xx.properties in IDE](/blog/spring-boot/messages_in_ide.png)

### 3. Configure resolving locale from requests

The default locale resolver is `AcceptHeaderLocaleResolver` which resolves the locale from the `Accept-Language` header.
You can change this by setting the `spring.mvc.locale-resolver` property in your `application.properties` file or by
providing your `LocaleResolver` bean,
creating `LocaleChangeInterceptor` and registering it via `addInterceptors` method (see `WebMvcConfigurer` class).

```java
@Bean
public LocaleResolver localeResolver() {
    SessionLocaleResolver sessionLocaleResolver=new SessionLocaleResolver();
    sessionLocaleResolver.setDefaultLocale(Locale.of("en"));
    return sessionLocaleResolver;
}

@Bean
public LocaleChangeInterceptor localeChangeInterceptor() {
    LocaleChangeInterceptor localeChangeInterceptor=new LocaleChangeInterceptor();
    localeChangeInterceptor.setParamName("lang");
    return localeChangeInterceptor;
}

@Override
public void addInterceptors(InterceptorRegistry registry) {
    registry.addInterceptor(localeChangeInterceptor());
}
```

### 4. Create HTML template with Thymeleaf

If you want to get an HTML document with translated messages, for example, to send it via email, you can use Thymeleaf.
If you are not familiar with Thymeleaf, you can read more about
it [here](https://www.thymeleaf.org/doc/tutorials/3.0/usingthymeleaf.html).
In short, Thymeleaf is a modern server-side Java template engine for both web and standalone environments.

```html
<!doctype html>
<html xmlns="http://www.w3.org/1999/xhtml" th:attr="lang=${lang}">

<head>
  <title>Spring Boot Email Example</title>
</head>

<body>
<header>
  <h1 th:utext="#{title(${userName})}"></h1>
</header>

<article>
  <p th:text="#{message}"></p>
  <a th:href="${url}" th:text="#{linkText}"></a>
</article>
<footer>
  <p th:text="#{footerText}"></p>
</footer>
</body>

</html>
```

#### Quick Thymeleaf guide:

- `th:attr="lang=${lang}"` - sets the language of the document
- `th:utext="#{title(${userName})}"` - gets a message with `title` key and inserts the value of the `userName` variable
- `th:text="#{message}"` - gets a message with `message` key
- `th:href="${url}"` - inserts a value of the `url` variable
- You can use `th:utext` instead of `th:text` to avoid escaping HTML characters.
- You can use `th:attr` to set the `lang` attribute on the `html` tag.

You can use [https://mjml.io](https://mjml.io) to create responsive HTML emails for free.

## Localized texts

Use `MessageSource` to get translated messages. This is the default way to get translated messages in Spring Boot.

```java
import org.springframework.context.MessageSource;

@Autowired
private MessageSource messageSource;

@Test
void shouldGetTranslatedTextFromLocalFileAndLocale() {
    //given
    Locale locale=Locale.of("pl","PL");

    //when
    String titleTextWithArgument=messageSource.getMessage("title",new Object[]{"Foo Bar"},locale);

    //then
    assert titleTextWithArgument.equals("Hej Foo Bar!");
}
```

## Localized API exceptions

You can also return translated API exceptions by using standard Spring Boot `@ControllerAdvice`.
For this purposes, I created `ErrorController` with two methods annotated with `@ExceptionHandler` to catch exceptions.

- `@ExceptionHandler(Exception.class)` - catches all exceptions not caught by other methods
- `@ExceptionHandler(IllegalArgumentException.class)` - catches `IllegalArgumentException` exceptions

Both methods gets `Locale` from `LocaleContextHolder` and returns translated message from `messages_xx.properties` file
using `MessageSource` bean.

```java

@RestControllerAdvice
public class ErrorController
{
  @Autowired
  private MessageSource messageSource;

  @ExceptionHandler(Exception.class)
  @ResponseStatus(code = HttpStatus.INTERNAL_SERVER_ERROR)
  public ResponseEntity<ApiError> exception()
  {
    String message = getLocalizedMessage("exception.internalServerError");
    HttpStatus status = HttpStatus.INTERNAL_SERVER_ERROR;
    return ResponseEntity
            .status(status)
            .body(new ApiError(message, status));
  }

  @ExceptionHandler(IllegalArgumentException.class)
  @ResponseStatus(code = HttpStatus.BAD_REQUEST)
  public ResponseEntity<ApiError> badRequest()
  {
    String message = getLocalizedMessage("exception.badRequest");
    HttpStatus status = HttpStatus.BAD_REQUEST;
    return ResponseEntity
            .status(status)
            .body(new ApiError(message, status));
  }

  private String getLocalizedMessage(String translationKey)
  {
    Locale locale = LocaleContextHolder.getLocale();
    return messageSource.getMessage(translationKey, null, locale);
  }
}
```

By default, Spring Boot uses `Accept-Language` header to resolve user locale,
but in this
tutorial [we changed this behavior by registering custom `LocaleChangeInterceptor` bean](#3-configure-resolving-locale-from-requests)
.
To change the language of exception, you need to use `lang` parameter, e.g. `/api/my-health?lang=pl_PL`.

![Translated Spring Boot exceptions](/blog/spring-boot/translated-api-exceptions.mp4)

The number of ways to return translated messages is endless,
but the solution above might be one of the best ones
as we keep all the logic and translation keys for exceptions in one place.

## Localized HTML content (Thymeleaf)

Use `ThymeleafEngine` bean to render HTML with translated messages. This is _probably_ the most
popular way to render HTML with translated messages in Spring Boot.

```java
@Autowired
private TemplateEngine templateEngine;

public String renderHtmlFromTemplate(Locale locale,String userName)
{
    Context context=new Context();
    context.setLocale(locale);
    context.setVariable("userName",userName);
    context.setVariable("lang",locale.getLanguage());
    context.setVariable("url","https://simplelocalize.io");
    return templateEngine.process("my-html-template",context);
}
```

![render custom HTML with translated texts](/blog/spring-boot/ide-with-spring-boot.png)

## Localized web pages (Thymeleaf)

You can also return translated web pages (HTML) by using standard Spring Boot `@Controller`.
Spring Boot will automatically resolve user locale and render HTML from `my-html-template.html` template with translated
messages.

This is the default way to return translated web pages in Spring Boot.

```java
@Controller
public class WelcomeController
{
  @GetMapping("/welcome")
  public String renderHtmlFromTemplate(Model model)
  {
    model.addAttribute("userName", "Jakub");
    return "my-html-template";
  }
}
```

Run the application and open `http://localhost:8080/welcome` in your browser.
You can change the language by adding `?lang=pl_PL` to the URL.

![Changing the 'lang' query parameter in Spring Boot](/blog/spring-boot/change-language-parameter.mp4)

## Resources

- [Spring Boot: Internationalization](https://docs.spring.io/spring-boot/docs/2.1.13.RELEASE/reference/html/boot-features-internationalization.html)
- [Spring Boot 3.0: Internationalization using MessageSource](https://docs.spring.io/spring-framework/docs/3.0.0.M4/spring-framework-reference/html/ch03s13.html)
- [Spring Boot: WebMvcConfigurer](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/web/servlet/config/annotation/WebMvcConfigurer.html#addInterceptors(org.springframework.web.servlet.config.annotation.InterceptorRegistry))
- [Spring Boot: LocaleResolver](https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/web/servlet/LocaleResolver.html)
- [Full code: simplelocalize/spring-boot-i18n](https://github.com/simplelocalize/spring-boot-i18n)


Translation Hosting

SimpleLocalize CLI

REST API

Auto-translation

Alternative translations

Java

Java 19: Internationalization

Spring Boot 3.0: Internationalization