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


Discover the power of `toLocaleString()` function in JavaScript. Format numbers, currencies, and units without any 3rd party localization library.
In simple words, the `toLocaleString()` method converts a number into a string, using locale format. By default, it uses locale from web browser language, but you can specify it manually.   



## Syntax 
```js
number.toLocaleString(locale, options);
```

## Parameters
- `locale` (optional) - if not provided, then the method will use the host environment's current locale (e.g., : default browser language)
- `options` (optional) - object with formatting options

```js
var exampleNumber = 123456.789;

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

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

### Limit to two significant digits
```js
const price = 123456.789;
price.toLocaleString('en-IN', { 
  maximumSignificantDigits: 2 
});
// output: 1,23,000
```

### Use default locale and custom number formatting

Put `undefined` as first parameter, to use default locale set in browser.

```js
const price = 30000.65;
price.toLocaleString(undefined, { 
  minimumFractionDigits: 2, 
  maximumFractionDigits: 2 
});
// English output: 30,000.65
// German output: 30.000,65
// French output: 30 000,65
```

### Change formatting style

Style property can have 3 different values:
- `decimal` (default)
- `currency`
- `percent`
- `unit`

In this article, we go through every style.

## Style: Currencies

Use `style` property in options object with value `currency` to format number into a string.

```js
const price = 123456.789;
price.toLocaleString('de-DE', { style: 'currency', currency: 'EUR' });
// output: 123.456,79 €

price.toLocaleString('ja-JP', { style: 'currency', currency: 'JPY' });
// output: ￥123,457
```

You can adjust `currencyDisplay` property to change currency formatting. Possible values are: 
- `symbol` (default)
- `code` 
- `name`

```js
const price = 123456.789;
price.toLocaleString('de-DE', { 
  style: 'currency', 
  currencyDisplay: 'code', 
  currency: 'EUR' 
});
// output: 123.456,79 EUR

price.toLocaleString('ja-JP', { 
  style: 'currency', 
  currencyDisplay: 'name', 
  currency: 'JPY' 
});
// output: 123,457円
```



## Style: Percentages

Percentage localization is a non-trivial task in some languages. 
Not in every language, percentage sign comes after a number. 
For example, in Arabic languages.  

```js
const value = 0.767;
value.toLocaleString('pl-PL', { style: 'percent' });
// output: 77%

value.toLocaleString('ar-SA', { style: 'percent' });
// output:؜ ٧٣٪ ؜
```

## Style: Units

Units style is one of the most understated JavaScript locale features. It allows you to format 
number into any popular units with proper formatting for given locale.

### Example with `liter` unit

Use `unit` property in options object to set a desired unit.

```js
const value = 3;
value.toLocaleString('pl-PL', {
    style: 'unit',
    unit: 'liter'
});
// output: 3 l
```

You might also want to adjust `unitDisplay` property to show full word instead just one letter.

```js
const value = 3;
value.toLocaleString('pl-PL', {
    style: 'unit',
    unit: 'liter',
    unitDisplay: 'long'
});
// output: 3 litry
```

The shortest version you will get with `narrow` value in `unitDisplay`.

```js
const value = 3;
value.toLocaleString('pl-PL', {
    style: 'unit',
    unit: 'liter',
    unitDisplay: 'narrow'
});
// output: 3l
```

### List of JavaScript number locale units

Below, you can check all possible values for `unit` property.

<div class="units-table">

`unit` value | 
--- | 
acre
bit
byte
celsius
centimeter
day
degree
fahrenheit
fluid-ounce
foot
gallon
gigabit
gigabyte
gram
hectare
hour
inch
kilobit
kilobyte
kilogram
kilometer
liter

`unit` value | 
--- | 
megabit
megabyte
meter
mile
mile-scandinavian
milliliter
millimeter
millisecond
minute
month
ounce
percent
petabyte
pound
second
stone
terabit
terabyte
week
yard
year

</div>

### Kilometer per hour

You can combine two values using `per` keyword, like `X-per-Y`. For example, `kilometer-per-hour`.
JavaScript will choose the best-fit localized pattern to format this compound unit.

```js
const speed = 50.2137;
speed.toLocaleString('pt-PT', {
  style: 'unit',
  unit: 'kilometer-per-hour'
});
// output: 50,214 km/h
```

### Terabyte per gram

The `unit` property doesn't have to make sense, it accepts any combination. 😊
```js
const value = 50.2137;
value.toLocaleString('pl-PL', {
  style: 'unit',
  unit: 'terabyte-per-gram',
  unitDisplay: "long"
});
// output: 50,214 terabajta na gram
```


## Resources:
- [tc39.es/ecma402](https://tc39.es/ecma402)
- [React Localization libraries](/blog/posts/the-most-popular-react-localization-libraries/)


Number formatting in JavaScript


## Code-splitting for resources

Code-splitting is a built-in function in many code bundlers like [Webpack](https://webpack.js.org). It's used mostly to lazy load only required JavaScript code or other resources.
It helps in improving application performance by loading only required parts of the application, instead of fetching all resources at once.
This is a perfect solution for localization purposes to load translations for only one language instead of all of them to speed up your web application.

> Medium-sized web application with about 1000 unique translation keys can contain about 50kb translated messages for one language. If you would
> support 10 languages in your app, whole translation file could have size nearly 1 megabyte.

Learn more about [code-splitting in React](https://reactjs.org/docs/code-splitting.html).

## How to lazy load JSON file in React?

Here is the asynchronous function TypeScript, which accepts `languageKey` as a `string` and returns a loaded JSON file as an JavaScript object.

```typescript
const loadJson = (languageKey: string): Promise<any> => {
  return new Promise((res, rej) => {
    import(`../assets/i18n/${languageKey}-messages.json`).then((data) => {
      res(data?.default);
    });
  });
};
```

## How to use lazy load in React app?

Here is the full example code for lazy loading translations from local JSON files. The code is written in TypeScript,however, it should be easy to convert into plain JavaScript.

```typescript jsx
import {useState} from "react";

const [locale, setLocale] = useState('en-US');
const [messages, setMessages] = useState({});

// first useEffect
useEffect(() => {
  const locale = window.navigator.language;
  setLocale(locale);
}, []);

// second useEffect
useEffect(() => {
  loadJsonAsync = async () => {
    const messages = await loadJson(locale);
    setMessages(messages);
  }
  loadJsonAsync();
}, [locale])

// use your messages
```

React will invoke:
- the first `useEffect` hook only **once on every page re-render**. We are getting the language from web browser. Learn more about [navigator.language](https://developer.mozilla.org/en-US/docs/Web/API/Navigator/language) object.

- the second `useEffect` hook when `locale` value is changed to lazy load different JSON file with translations.

> You cannot invoke async functions in `useEffect` React hook, that is why we create a new `loadJsonAsync` function.

Check example [how to load translations from backend](https://github.com/simplelocalize/react-intl-simplelocalize/blob/master/src/index.js) using a standard fetch API.


## Use loaded JSON messages with IntlProvider

To use loaded JSON messages with FormatJS, you can simply pass `locale` variable and `messages` object as props
to IntlProvider.

```tsx
<IntlProvider 
  locale={locale} 
  messages={messages}
>
          {children}
</IntlProvider>
```

`children` variable should contain your React component or even a whole application (e.g., `<App/>`) in which you want to provide translations.


How to use code splitting with JSON files in React application


The [CSA Research study](https://csa-research.com/Blogs-Events/Blog/do-b2b-buyers-value-localization) shows that 66% of business users are more likely to pay more for a localized service than one in a foreign language.
The majority prefer to consume and interact with content in their native language, as it feels more natural and simply right, even for users with advanced English proficiency. The preference for localized products is well noted in software localization.

As you can see, internationalization of your project is critical for its success, if you plan to go to market in a different country. To take that step and introduce i18n support in your project, there are a few important thighs to consider while searching for the right tools. In this blog post we will cover one of them, a very base for proper software localization, which is localization library.

You can access our full [list of localization libraries and tools on Github](https://github.com/jpomykala/awesome-i18n). You are welcome to [add your resources](https://github.com/jpomykala/awesome-i18n) as a pull requests or just [create a new issue](https://github.com/jpomykala/awesome-i18n/issues/new).

## Top React localization libraries

See our list of the best React libraries we gathered. We focused mainly on ReactJS, React Native and Expo libraries.

### 1. FormatJS

[FormatJS](https://formatjs.io) provides i18n and l10n support for web applications with several packages, such as react-intl, which is a package specifically designed for use with React.
React-intl provides React components and utilities for formatting messages, dates, times, and numbers according to different locales. It also supports pluralization and gender agreement.

![FormatJS library](/blog/react-i18n-libraries/format-js.png)

#### See also
- [Integration guide: translations hosting](/docs/integrations/format-js/) - check how to use SimpleLocalize with FormatJS library
- [Extract i18n keys from FormatJS project](/docs/cli/i18n-keys-extraction/) - learn more about message extraction done by SimpleLocalize CLI
- [Blog post: FormatJS and React application localization](/blog/posts/formatjs-reactjs-internationalization/) - blog post about FormatJS translation management with SimpleLocalize
- [Github repository: example project](https://github.com/simplelocalize/simplelocalize-react-intl) - example project code with configured FormatJS
- [Live demo](https://react-intl.simplelocalize.io) - see live demo of FormatJS (react-intl) and SimpleLocalize integration


### 2. next-translate

[next-translate](https://github.com/vinissimus/next-translate) is a lightweight translation library for Next.js. It provides an easy way to add i18n support to Next.js projects, with features such as automatic language detection, dynamic translations, and support for multiple locales.

It all started when the developers realised how important is i18n for SEO, and thanks to the community, Next.js decided to introduce internationalized routing.
[Internationalized routing became available](https://nextjs.org/blog/next-10#internationalized-routing) in Next.js 10.

![next-translate](/blog/react-i18n-libraries/next-translate.png)

#### See also
- [Blog post: How to translate NextJS app with next-translate](https://simplelocalize.io/blog/posts/next-translate/) - step-by-step instruction for localization with next-translate


### 3. react-i18next

[React-i18next](https://react.i18next.com/) is one of the most popular localization libraries among React developers.
Commonly used in React localization.
It can be used with React Web and React Native.
i18next was primary created for React only,
but the community gathered among the library created integrations for other frontend frameworks such as AngularJS,
Vue.js and more.

#### See also
- [Integration guide: translations hosting](/docs/integrations/i18next/) - check how to use SimpleLocalize with the i18next library
- [Extract i18n keys from i18next library](/docs/cli/i18n-keys-extraction/) - use SimpleLocalize CLI to find translation keys used in the project
- [Blog post: i18next in 3 steps](/blog/posts/i18next-reactjs-localization/) - blog post about integrating SimpleLocalize with i18next
- [Github repository: example project](https://github.com/simplelocalize/simplelocalize-i18next) - sample project with configured i18next with **'http-backed'** and **'loadpath'**
- [Live demo](https://i18next.simplelocalize.io) - see live demo of i18next with configured http-backend and 'loadpath'.

![react localization](/blog/i18next-simplelocalize.png)

### 4. LinguiJS

[LinguiJS](https://github.com/lingui/js-lingui) is a JavaScript library for internationalization and localization of web applications. It offers message extraction and formatting, supports dynamic content, and integrates with popular front-end frameworks like React and Vue.js, Node.js, and Angular.
It provides a comprehensive and well optimized set of tools for developers to create applications that can be easily adapted to different languages

[Comparision of LinguiJS with react-intl](https://lingui.dev/misc/react-intl)

![next-translate](/blog/i18n-linguijs.png)


### 5. react-native-localize

[React-native-localize](https://github.com/zoontek/react-native-localize) is a library for React Native that provides a set of tools for internationalizing and localizing mobile applications. It offers a range of features such as date and time formatting, number formatting, and text direction based on the user's locale. It also provides a simple API for translating strings in your application, making it easy to adapt your app to different languages and cultures.

This library is a toolbox for your React Native app localization.

![react-native-localize](/blog/react-i18n-libraries/react-native-localize.png)


### 6. FormatJS CLI

[FormatJS CLI](https://formatjs.io/docs/tooling/cli/) extracts messages from a project with FormatJS library. Learn [how to upload extracted translation messages to SimpleLocalize](/docs/integrations/format-js-cli).

![formatjs cli](/blog/react-i18n-libraries/i18n-formatjs-cli.png)


### 7. react-i18nify

[React-i18nify](https://github.com/sealninja/react-i18nify) is a simple group of translation and localization components and helpers for your React application.

![react-i18nify](/blog/react-i18n-libraries/react-i18nify.png)



### 8. react-littera

[react-littera](https://github.com/Assembless/react-littera) is a fairly new library for React localization.
It was created to make maintaining and managing translations easier. It allows placing translations right beside your component, as well as storing translations globally. Littera's structure was inspired by react-jss.

![react littera for managing translations](/blog/react-i18n-libraries/react-littera.png)

```shell
npm install --save @assembless/react-littera
```

### 9. react-persian

[react-persian](https://github.com/evandhq/react-persian) is a library for Persian localization in React. It provides a set of components for Persian localization.
Are you developing an application for a Persian audience? You should definitely check this library out.

![react-persian](/blog/react-i18n-libraries/react-persian.png)



### 10. react-translate

[bloodyowl/react-translate](https://github.com/bloodyowl/react-translate) is a set of React utilities for simple i18n handling.
The library is a bit outdated, last commit was in 2019, and last release is dated to end of 2016.

**If some reason you didn't like FormatJS, then the library is worth checking.**

![react-translate](/blog/react-i18n-libraries/react-translate.png)


### 11. react-translated

[react-translated](https://github.com/amsul/react-translated) is a **dead simple way to add complex translations** in a React project.
The library is a bit outdated but definitely work checking!

![react-translated](/blog/react-i18n-libraries/react-translated.png)


### 12. react-intl-hooks (for FormatJS)

[React-intl hooks](https://github.com/CreateThrive/react-intl-hooks) is a small and fast library
that you can use to replace FormatJS components.
It combines the great things about react-intl along with React hooks.
It provides a `t` function, which works like the `t` function in the i18next library.

```tsx
const t = useFormatMessage();
t({ id: 'learn-react', defaultMessage: 'Learn React' })
```

![react-intl hooks](/blog/react-i18n-libraries/react-intl-hooks.png)

```shell
npm install --save react-intl-hooks
```

### 13. typesafe-i18n

[typesafe-i18n](https://github.com/ivanhofer/typesafe-i18n) is an opinionated, fully type-safe, lightweight localization library for TypeScript and JavaScript projects with no external dependencies.

![typesafe-i18n - demo](/blog/typesafe-i18n-demo.mp4)

```shell
npm install --save typesafe-i18n
```

### 14. SimpleLocalize CLI + TMS

SimpleLocalize allows you to upload and manage translation keys in the cloud.
The free account allows you to host up to 250 translation keys,
and you can test it for bigger files during a 14-day trial.
You can [create your account here](/register/).

#### 1. Upload translations

Upload your translation files using [SimpleLocalize CLI](/docs/cli/upload-translations/), [API](/docs/api/update-translations/) or [import translations](/docs/general/import/) using our web app and file format of your preference.

![How to upload translation files with command-line tool](/docs/cli-upload-translations.mp4)

#### 2. Translate in editor

Add new languages and translations in a simple [translation editor](/docs/general/translation-editor/), adjusted to the whole team's needs. Show code or key descriptions, adjust editor view to your preferences, and work in a developer-friendly environment.

![How to change translation in Translation Editor](/blog/simplelocalize-editor-translate.mp4)

You can use DeepL or Google Translate to [translate texts automatically](/docs/general/auto-translation/).

#### 3. Download translations

When the translations are ready, you can download them in multiple ways. Export translations inside SimpleLocalize or use or CLI and API to get ready to use translation files.

![How to download translation using command-line tool](/docs/cli-download-translations.mp4)

#### 4. Localization hosting

Check also [our translation hosting](/docs/general/translation-hosting/) option
to keep your localization files in the cloud.
Access them easily with superfast CDN and fetch your updated translations anywhere and anytime.


#### See also:
- [i18next: integration guide](/docs/integrations/i18next/)
- [FormatJS: integration guide](/docs/integrations/format-js/)
- [FormatJS CLI: integration guide](/docs/integrations/format-js-cli/)
- [Docs: translation hosting](/docs/general/translation-hosting/)
- [Docs: Getting started with CLI](/docs/cli/get-started/)

👋 Thanks for reading!


Translation Hosting

SimpleLocalize CLI

REST API

Auto-translation

Alternative translations

Javascript

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

Number formatting in JavaScript

How to use code splitting with JSON files in React application

List of i18n libraries for React, React Native, and NextJS