# Localization

Each module should have it's own POEditor project.
Adding the POEDITOR_PROJECT_ID and POEDITOR_API_TOKEN to your `.env` file will allow you to start working with translations locally. The CLI automatically downloads the English terms and translations to the `locale/default.json` file ( if it does not exist ).

`default.json` contains all English terms and translations used in your module. If you are adding a new string to be translated, add a key and the English text.

```json
{
    "addToPlaylist": "Add to playlist"
}
```

**NOTE! Only English terms and translations are modifiable in your project. The other languages are translated using POEditor.**

When the module is built and deployed, new terms in `default.json` are pushed to POEditor. Deleted terms are removed from the whole POEditor project. Also, renaming a English term will delete the translations related to the old name.

To translate a string in the current language, use the `formatMessage` function from `@orchard/frontend-localization`.

```jsx
import { formatMessage } from '@orchard/frontend-localization';

const AddButton = ({ onClick }) => (
    <button onClick={onClick}>{formatMessage('addToPlaylist')}</button>
);
```

## Translation context

To allow for more verbose translation contexts, the `default.json` may have nested terms. The path e.g. 'header.button' will then be shown in POEditor.

```json
{
    "header": {
        "button": "I'm in the header!"
    },
    "footer": {
        "button": "I'm in the footer!"
    }
}
```

```jsx
formatMessage('header.button');
```

Example: [frontend-catalog - default.json](https://github.com/theorchard/frontend-catalog/blob/master/locale/default.json)

## String interpolation

```json
{
    "deleteXItems": "Delete {count} {type}."
}
```

```jsx
formatMessage('deleteXItems', { count: 10, type: 'products' });
```

## Plural terms

Using terms with plural format is supported using special properties: "one", "other".

```json
{
    "deleteXItems": {
        "one": "Delete item.",
        "other": "Delete {count} items."
    }
}
```

```jsx
formatMessage('deleteXItems', { count: 10 }); // "Delete 10 items."
formatMessage('deleteXItems', { count: 1 }); // "Delete item."
```

**NOTE** when using plurals, always include the `{count}` parameter.

---

View the [frontend-localization](api/frontend-localization.md) api for available i18n helper functions.