What is ICU? Our guide for ICU message formatting and syntax.


## 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.

![download messages_xx.properties files via simplelocalize cli](/blog/spring-boot/java-properties-download.gif)

### 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");
    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 exception](/blog/spring-boot/translated-api-exceptions.gif)

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 lang parameter in spring boot](/blog/spring-boot/change-language-parameter.gif)

## 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)


Spring Boot 3.0: Internationalization


Localizing your product is a great way to reach new markets and generate more revenue. However, it will only be beneficial if you avoid the most common problems with localization.
There are some simple and easy-to-follow tips that you can utilize to make sure that your localization process is successful. 

## Give your texts enough space

If you have tight layouts, a rough rule of thumb is to double the English text and make sure it fits. 
Then you will usually have enough space for translations. 
Russian and German tend to have the longest translations, and the longest words. Get familiar with the shy-hyphen `&shy;` character. You put it in the word's HTML, and it will only break the word/show the hyphen when necessary. 
You can also Google: "[online hyphenation tool](https://www.google.com/search?q=online+hyphenation+tool)" 
so you know the appropriate places to break the word. Here are some example applications:

- [ushuaia.pl](https://www.ushuaia.pl/hyphen/?ln=en)
- [hyphenation24.com](https://www.hyphenation24.com/)
- [hyphenator.net](https://www.hyphenator.net/)
- [juiciobrennan.com/hyphenator](https://juiciobrennan.com/hyphenator/)

![number translations](/blog/number-translations-problem.jpg)

## Number translations

You need to translate numbers with decimals and commas because they are reversed in some languages.
For example: period appears as a comma, comma as a period.

If you are a JavaScript developer, then you can simply use 
[Number object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/toLocaleString) 
to format numbers. See example below:

```js
var exampleNumber = 123456.789;

exampleNumber.toLocaleString('pl-PL');
// output: 123.456,789

number.toLocaleString('ar-EG');
// output: ١٢٣٤٥٦٫٧٨٩
```

## Percent sign problem

The same goes for percent signs. Sometimes the % shows before the number, and not after also there might be a space between the number and percentage sign.
English style guides recommend writing the percent sign (%) following the number with no space between (e.g., 50%) however this might differ for different languages.
- In Turkish and some other Turkic languages, the % sign precedes rather than follows the number without an intervening space.
- In Persian the % sign may appear before or after the numeric value, in either case without a space.
- In Arabic, the % sign is to the left of numbers, as numbers are written from right-to-left. This means that the % sign is to the left of a number. Usually, there will not be a space between this % sign and the number.

## Watch out for Greek question marks
The Greek question mark (;) is often mistaken for a semicolon (;). 
The former marks the end of a sentence or phrase, while the latter is used to separate clauses in the same sentence.

![greek question makr](/blog/greek-question-mark-intelij-idea.png)

## Keep datetime in UTC 
- Always keep datetime in database in UTC. 
- Always return datetime from backend in UTC. 
- Adjust datetime on UI layer using timezone information from user or web browser. 
- Accept datetime in backend with any timezone.

You don't need any special library to format time from UTC to local for users. You can
use standard [JavaScript Date object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) like below:

```js
new Date('2010-10-04T09:48:11.000000Z').toLocaleString('en-US', {
  timeZone: 'Asia/Calcutta'
});
```

The main benefit to that is that the time is always guaranteed to be consistent. 
However, if you would like to reproduce some bug for a user in different timezone, it might be more challenging.
You will be forced to change timezone in your web browser to get the same data as your users sees. 


Localization: Tips & Tricks


## Background

In this article, I will show you how to create a multi-language landing page in GatsbyJS.
I assume you already set up a Gatsby project, and we will start right from adding multi-language pages.

> Check our [template repository on GitHub](https://github.com/simplelocalize/multi-language-gatsby-example). 

## Install dependencies

I will use FormatJS library as it's one of [the most popular React library for internationalization](/blog/posts/the-most-popular-react-localization-libraries), and it plays nice 
with Gatsby plugin system.

```bash
# Npm users
npm install --save react-intl

# Yarn users
yarn add react react-intl
```

## Create i18n configuration file

Create a `i18n.js` file in your `src` directory to keep all i18n configuration in one place.

```jsx
const languages = ['en', 'pl', 'es'];
const defaultLanguage = 'en';

exports.defaultLanguage = defaultLanguage;
exports.languages = languages;
```

## Add utility functions

Create a new file with utility functions. I named it `linkUtils.js` and I put this next to `i18n.js` file in the `src` directory.

```jsx
import {defaultLanguage, languages} from "./i18n";

const getTranslatedPath = (pathname, to) => {
  const currentPageLanguage = getCurrentPageLanguage(pathname);

  let languagePath = '';
  const isDefaultLanguage = defaultLanguage === currentPageLanguage;
  if (!isDefaultLanguage) {
    languagePath = '/' + currentPageLanguage
  }


  let outputPath = `${languagePath}${to}`;

  const hasTrailingSlash = outputPath.endsWith("/");
  if (!hasTrailingSlash) {
    outputPath += "/";
  }

  return outputPath;
}

const getCurrentPageLanguage = (pathname) => {
  const pathElements = pathname.split("/");
  for (let element of pathElements) {
    for (let language of languages) {
      if (element === language) {
        return language;
      }
    }
  }
  return defaultLanguage;
};

export {getTranslatedPath, getCurrentPageLanguage};
```

- `getTranslatedPath` Function returns a route to a page with the same language as the current page.
- `getCurrentPageLanguage` Function returns language from current page path. 

## Create custom link component

To give a user to navigate through our website and keep the page language, we need to create a custom `<a/>` element.

```jsx
import React from "react";
import {Location} from '@reach/router';
import {getCurrentPageLanguage, getTranslatedPath} from "./linkUtils";

const LinkTranslated = ({children = [], className = "", href = "/"}) => {
  return (
    <Location>
      {locationProps => {
        const {pathname = ""} = locationProps.location;
        return <a className={className}
                  href={getTranslatedPath(pathname, href)}
                  hrefLang={getCurrentPageLanguage(pathname)}
        >
          {children}
        </a>;
      }}
    </Location>
  );
};

export default LinkTranslated;
```

Now we can use `LinkTranslated` same as a regular `<a/>` tag from HTML.
We can pass a `href` property with base link to some page, and it will be converted into a translated link.

Learn more about [hrefLang attribute](/blog/posts/what-is-hreflang/).

> I used `Location` component from `@reach/router`, to get access to the `location` object. 

## Add a wrapper for `IntlProvider`

```jsx
import React from "react";
import {IntlProvider} from "react-intl";

function SimpleLocalize(props) {
  const language = props.pageContext.language;
  const messages = props.pageContext.messages;
  return (
    <IntlProvider
      locale={language}
      messages={messages}>
      {props.children}
    </IntlProvider>
  );
}

export default SimpleLocalize;
```

The main role of this component is to simplify a usage of `<IntlProvider/>` on every page.

## Add translations

Create a `i18n-translations.json` file with translations for all languages.

```json
{
  "en" : {
    "welcome-on-our-website" : "Welcome on our multi-language website",
    "hello-world" : "Hello World!",
    "about-us" : "About us",
    "learn-more-about-us" : "Learn more about us",
    "homepage" : "Homepage"
  },
  "pl" : {
    "welcome-on-our-website" : "Witamy na naszej wielojęzycznej stronie internetowej",
    "hello-world" : "Witaj Świecie!",
    "about-us" : "O nas",
    "learn-more-about-us" : "Dowiedz się więcej o nas",
    "homepage" : "Strona główna"
  },
  "es" : {
    "welcome-on-our-website" : "Bienvenido a nuestro sitio web multilingüe",
    "hello-world" : "Hola, mundo.",
    "about-us" : "Sobre nosotros",
    "learn-more-about-us" : "Más información sobre nosotros",
    "homepage" : "Página web"
  }
}
```

Managing a big JSON file like this might be hard and done only by a software team. This is the reason we created 
[SimpleLocalize](/) where you can manage JSON files like this with ease, automatically upload and download them and use 
Google Translate or DeepL to auto-translate the texts. [Try it for free for 7 days!](/register)

## Configure multi-language page generation

Now, edit your `gatsby-node.js` configuration file and override `onCreatePage` function like below.

```jsx
const messages = require("./i18n-translations.json")
const {languages, defaultLanguage} = require("./src/i18n");

exports.onCreatePage = async ({page, actions}) => {
  const {createPage, deletePage} = actions;
  return new Promise((resolve) => {
    let path = page.path;
    deletePage(page);

    for (let language of languages) {
      const isDefaultLanguage = language === defaultLanguage;
      if (!isDefaultLanguage) {
        path = '/' + language + page.path;
      }

      const pageForLanguage = Object.assign({}, page, {
        originalPath: page.path,
        path: path,
        context: {
          language,
          messages: messages[language]
        }
      });
      createPage(pageForLanguage)
    }
    resolve()
  })
};
```

Many things are happening here, right? Let start from the beginning.

- First of all, import `translations.json` file from root directory
- Use `deletePage` to remove default page created by Gatsby
- Iterate over all `languages` from `i18n.js` 
- Add `/{language}` to path if the language is not the default one
- Get translations for given `language` from `messages` object
- Add language and messages to a page context
- Use `createPage` to recreate a page with a new path and translations



## Create a first multi-language page

Create `index.js` in `/src/pages` directory and paste code below:

```jsx
import React from "react";
import {FormattedMessage} from "react-intl";
import LinkTranslated from "../LinkTranslated";
import SimpleLocalize from "../SimpleLocalize";

function IndexPage(props) {
  return (
    <SimpleLocalize {...props}>
      <h1>
        <FormattedMessage
          id="hello-world"
          defaultMessage="Hello World!"
        />
      </h1>

      <p>
        <FormattedMessage
          id="welcome-on-our-website"
          defaultMessage="Welcome on our multi-language website"
        />
      </p>

      <LinkTranslated
        className="btn btn-link"
        href="/about"
      >
        <FormattedMessage
          id="learn-more-about-us"
          defaultMessage="Learn more about us"
        />
      </LinkTranslated>
      <ul>
        <li><a href="/">English (Default)</a></li>
        <li><a href="/pl/">Polish</a></li>
        <li><a href="/es/">Spanish</a></li>
      </ul>

    </SimpleLocalize>
  );
}
export default IndexPage
```

`SimpleLocalize` Component will provide a `<IntlProvider/>` and `intl` object for `<FormattedMessage/>` components.

## Create second multi-language page 

Create file `about.js` in `/src/pages` directory and paste code like below:

```jsx
import React from "react";
import SimpleLocalize from "../SimpleLocalize";
import {FormattedMessage} from "react-intl";
import LinkTranslated from "../LinkTranslated";

function AboutPage(props) {
  return (
    <SimpleLocalize {...props}>
      <h1>
        <FormattedMessage
          id="about-us"
          defaultMessage="About us"
        />
      </h1>

      <LinkTranslated
        className="btn btn-link"
        href="/"
      >
        <FormattedMessage
          id="homepage"
          defaultMessage="Homepage"
        />
      </LinkTranslated>
    </SimpleLocalize>
  );
}
export default AboutPage;
```


## Result

Now, start your project with `npm run develop` and you should see 

![Multi-language Gatsby project example](/blog/gatsby-multi-language-project.png)

Full code can be found on GitHub: [github.com/simplelocalize/multi-language-gatsby-example](https://github.com/simplelocalize/multi-language-gatsby-example)



### Message extraction

![Uploading extracted translation keys to translation editor](/blog/uploading-extracted-translation-keys-in-json-file.jpg)

In the repository, you will also find [additional scripts in `package.json`](https://github.com/simplelocalize/multi-language-gatsby-example/blob/master/package.json).

I installed `@formatjs/cli` as a `devDependency` to extract all translations and IDs from `<FormattedMessage/>` components.

```shell
## npm
npm install --save-dev @formatjs/cli

## yarn
yarn add -D @formatjs/cli
```

I used [simplelocalize-cli](/docs/cli/get-started/) to upload found IDs and download ready to use translations.

Scripts explanation:
- `npm run extract` script will extract translations to i18n-extracted.json
- `npm run sync` script will upload found translation keys from i18n-extracted.json and download the latest translations from the server to i18n-translations.json


> Once you change a translation in JSON file, you need to restart GatsbyJS to see the effect. Sometimes you might not see a changed translation, then you need to run `npm run clean` before `npm run develop`. 

### Editing translations in SimpleLocalize

Below you see a screenshot from a sample project which I [pushed on GitHub](https://github.com/simplelocalize/multi-language-gatsby-example). Now, I can manage all translations from one place, add more languages and use DeepL or Google Translate to automatically translate them and use in my Gatsby page. 

![Multi-language Gatsby project in SimpleLocalize](/docs/translate-project.gif)

Multi-language content with [properly used `hrefLang` attributes](/blog/posts/what-is-hreflang/) will score much higher in SEO results.


How to create a multi-language website in GatsbyJS?



The **translation** is the process of converting a text or message from one language to another. When it comes to translation, locale and language are two terms that are often used interchangeably. But what does locale mean? And how does it differ from the language in terms of translating texts and adjusting them to regional needs in each country?

This article will answer these questions and explore the uses for locale and language when translating apps and software into different languages around the world.

## How is Language different from Locale?

The question of how to translate from one language to another is not as simple as it may seem. Two primary factors must be addressed to create a complete translation: the language and the locale. 

The first factor, the language, is self-explanatory; this is what will actually be translated. However, there's more than meets the eye with the second factor - locale. 

Locale refers to regional settings such as currency symbols or date formats. One cannot simply translate a word for word without considering these additional parameters that make up an entire culture's way of life and understanding of their world around them.

![World](/blog/world-image.jpg)

## What is a locale?

In an era where digital globalization is on the rise, one of the most important aspects to consider when translating a product or app into another language is locale. What exactly does this mean? 

Locale involves cultural adaptation and tailoring your content for specific audiences in other countries. It means going beyond literal translations that might sound funny to native speakers of that region; instead, you need to get acquainted with their customs and habits to convey meaning without sounding too strange appropriately.

## How to deal with Locale?

Translating software and apps is a challenging task, as different languages have different rules. For example, the word "locale" can be translated to "Lokalität" in German or "locação" in Portuguese, but it cannot be translated into Russian because there is no equivalent word for this concept. 

When starting adjusting each app to local needs, consider those questions:

- How are measurements like currency, date, and time handled there?
- Are there any differences in the way documents are created?
- Does this region have any words/sayings that might mean something else for them than for you?

## Technical side of locale

In the code of an application or page, we write locale identifier as the language code (country) and region where the language variation is used. For example, the English language differs in different parts of the world, so to best adapt the text to the audience, we use words and phrases used in a given region. Thus, English, generally designated as *en*, may adapt in translation the forms for local variations of the language, e.g., *en-GB* for the UK, *en-AU* for Australia or *en-US* for the United States. 

![Locale translations for Spanish](/blog/locale-translations.png)

The format of the locale, the separator, depends on the environment used in the project. Standard separator is "-", but there as some exceptions. "-" will not work for Java which uses *_* instead, whereas *_* won’t work for Windows

```
language-REGION
es-ES
es-CL

language_REGION
es_ES
es_CL
```


## Conclusion

The process of translating apps and software for a global audience can be tricky. When you translate a product for one culture without taking the time to understand their culture as well, there will be some serious problems along the way—and nobody wants that. Understanding the role of locale is vital in the translating process and creating valuable content for your audience.


Language vs Locale: What's the difference?


React localization is one of the topics discussed vividly among developers. There are many [i18n libraries built for React, React Native, and NextJS](/blog/posts/the-most-popular-react-localization-libraries/), that focus on app internationalization. Website or app translation is so important because it positively affects the product visibility and performance, increases the customer base and satisfaction by creating a special relation. It's all thanks to **adjusting the product to their language, customs, and culture**. Developers have a great choice of tools and libraries that can help them in i18n of the product, and one of them is FormatJS. 

## About FormatJS

 FormatJS, originally yahoo/react-intl, is a localization and internationalization set of libraries built mainly for React apps. It helps in i18n process, focusing on **numbers, dates, and strings formatting**. It provides i18n tools and packages that help with localization and app translation management.

A sample i18n file structure in FormatJS looks like this: 

```bash
projectRoot
|-- src
|   |-- App.js
|-- lang
|   |-- en-US.json
|   |-- fr.json
|-- package.json
|-- .eslintrc.js
```

In `lang` we create json files with supported languages, for example, `en-US` or `fr`. FormatJS focuses or improving development process of app internationalization and helps in future translation management.

## How to translate React app with FormatJS?

The installation and translation process is quite straightforward. We will start with creating a sample project, then FormatJS installation and setup, and finally building and translating our app. Sounds fun, right? 😎

### Create a sample project

Let's start with something simple. I will create a new project using [create-react-app](https://github.com/facebook/create-react-app). Use NPM or Yarn like in the example below. 

```bash
yarn create react-app simplelocalize-react-intl-example
```

Or download the [demo app from GitHub repository](https://github.com/simplelocalize/simplelocalize-react-intl).

### Install dependencies

Add `react-intl` library to your newly created project.

```bash
# Using NPM
npm i -S react react-intl

# Using yarn
yarn add react react-intl
```

### Add Language Context

In this project, I will use `Context` to keep translations and option to change language in real-time. 

```jsx
import React from 'react';

const LanguageContext = React.createContext("en");

export default LanguageContext;
```

Read more about [React Context API](https://reactjs.org/docs/context.html).

### react-intl configuration

Let's create main configuration for i18n with react-intl and SimpleLocalize wrapper.

```jsx
// 📦 file: ./SimpleLocalize.js

import React from "react";
import {IntlProvider} from 'react-intl'
import LanguageContext from "./LanguageContext";

class SimpleLocalize extends React.Component {

  constructor(props) {
    super(props);
    this.state = {
      messages: undefined,
      language: "en"
    };
  }

  componentDidMount() {
    this.setupLanguageMessages(this.state.language);
  }

  setupLanguageMessages = (language) => {
    const projectToken = "5e13e3019cff4dc6abe36009445f0883";
    const translationsUrl = `https://cdn.simplelocalize.io/${projectToken}/_latest/${language}`;
    return fetch(translationsUrl)
      .then((data) => data.json())
      .then((messages) => this.setState({language, messages}));
  };

  render() {
    return (
      <LanguageContext.Provider
        value={{
          changeLanguage: (language) => this.setupLanguageMessages(language)
        }}>
        <IntlProvider
          locale={this.state.language}
          messages={this.state.messages}>
          {this.state.messages ? this.props.children : null}
        </IntlProvider>
      </LanguageContext.Provider>
    )
  }
}

export default SimpleLocalize;
```

This wrapper will keep translations in our `LanguageContext` and it will also provide a function to change language in fly.

## Translate your app with FormatJS and SimpleLocalize

Now, it's time to work on i18n and localization process. We use SimpleLocalize to extract translation keys and as a translation management and i18n online editor.


### Create project

Create a [SimpleLocalize.io](https://simplelocalize.io) project to get your unique `messages` variable. For this demo project, you can use the `messages` from the example above!

### Wrap your application

Now let's use our newly created `SimpleLocalize` wrapper to provide translations for React application.

```jsx
// 📦 file: ./index.js

import React from 'react';
import ReactDOM from 'react-dom';
import './index.css';
import App from './App';
import SimpleLocalize from "./SimpleLocalize";

ReactDOM.render(
    <SimpleLocalize>
      <App/>
    </SimpleLocalize>,
  document.getElementById('root')
);
```

Done! React will now fetch translations from SimpleLocalize CDN and provide them to your app. 
Let's check how to use it in the source code.

## Translating React app

Now, let's start using translations, and create a basic web page. 

### FormatJS setup

See below how to apply translations for your React app. For that, we will use FormattedMessage component which wraps up all translation keys.

```jsx
// 📦 file: ./App.js

import React from 'react';
import logo from './logo.svg';
import './App.css';
import {FormattedMessage} from "react-intl";
import LanguageContext from "./LanguageContext";

function App() {

  return (
    <LanguageContext.Consumer>
      {context => (<div className="App">
        <header className="App-header">
          <div>
            <p>
              <FormattedMessage id="USE_BUTTONS_BELOW"/>
            </p>
            <button onClick={() => context.changeLanguage("en")}>English</button>
            <button onClick={() => context.changeLanguage("es")}>Spanish</button>
            <button onClick={() => context.changeLanguage("pl")}>Polish</button>
            <hr/>
          </div>

          <img src={logo} className="App-logo" alt="logo"/>
          <p>
            <FormattedMessage id="DESCRIPTION"/>
          </p>

          <a
            className="App-link"
            href="https://simplelocalize.io"
            target="_blank"
            rel="noopener noreferrer"
          >
            <FormattedMessage id="LEARN_MORE"/>
          </a>
        </header>
      </div>)}
    </LanguageContext.Consumer>
  );
}

export default App;

```


### FormattedMessage component

`<FormattedMessage/>` usage is very easy:
```jsx
<FormattedMessage id="YOUR_TRANSLATION_KEY"/>
```

React will convert `FormattedMessage` tag into `span` tag and put concrete translation into it. You can also use `<FormattedHTMLMessage id="TRANSLATION_WITH_CSS"/>` which will also produce a message with HTML inside `span` tag.

A sample translation key could look like the following:

```shell
TRANSLATION_WITH_CSS = This is my <strong>text</strong>
```

### Switch between languages

In the presented example, I used `LanguageContext.Consumer` to provide function. This function can trigger language change and fetch proper messages from the CDN.

```jsx
 <LanguageContext.Consumer>
      {context => (<div className="App">
        <header className="App-header">
          <div>
            <p>
              <FormattedMessage id="USE_BUTTONS_BELOW"/>
            </p>
            <button onClick={() => context.changeLanguage("en")}>English</button>
            <button onClick={() => context.changeLanguage("es")}>Spanish</button>
            <button onClick={() => context.changeLanguage("pl")}>Polish</button>
            <hr/>
          </div>
          //...
        </header>
      </div>)}
    </LanguageContext.Consumer>
```

You need `Language.Consumer` tag only in places where you would like to change the language. It's not needed for `<FormattedMessages/>` tags.

### Let's try it!

Note that translation works in real-time! How cool is that? Very cool!

![React Localization with formatjs](/blog/formatjs_and_react_app_localization.gif)

[See live version](https://react-intl.simplelocalize.io)

Project code is available on [GitHub](https://github.com/simplelocalize/simplelocalize-react-intl).

## Translation management for FormatJS

FormatJS is a great tool for translating your React app. It is intuitive and not too complicated to introduce to your project. Using react-intl together with SimpleLocalize can really speed up the translation process with great [auto translation tools (DeepL or Google Translate)](https://simplelocalize.io/docs/general/auto-translation/), many integrations and easy to use [i18n online editor](https://simplelocalize.io/i18n-editor-online/). It's a great help in development process thanks to [SimpleLocalize CLI for FormatJS, which extracts all translation keys](/docs/integrations/format-js-cli) from your project with a simple command. 

![i18n online editor](/assets/translation-editor-interface.png)

Check our docs for [FormatJS integration](/docs/integrations/format-js/) in SimpleLocalize and translate your app in our feedback-driven app. Get in touch or send us your feedback at [contact@simplelocalize.io](mailto:contact@simplelocalize.io).


Translation Hosting

SimpleLocalize CLI

REST API

Auto-translation

Alternative translations

I18n