# Using Locale Groups to Group Similar Localizations


Locale Groups can be used to [add a group of individual locales](#adding-all-locales-individually-to-an-email) to an email at one time, and for adding a single translation for a [group of same-language locales](#adding-single-translation-for-locale-group).

## Creating Locale Groups

In the Administration dashboard, navigate to the
<a href="https://app.dyspatch.io/admin/locales/groups" target="_blank">Locales > Locale Groups</a> tab and select
**Create a Locale Group**.

![Locale Group menu item in the administration dashboard](https://docs.dyspatch.io/img/localizations/locale-groups-admin.png)

Name the locale group and add a description. Add localizations to the locale group by filtering localizations at the top
and selecting from the supported localizations list.

![Locale Group creation screen with select items, name, and description](https://docs.dyspatch.io/img/localizations/locale-groups-example.png)

Once you have selected all the localizations you want in the group, select the **Add Locales & Create Group** button.

<div class="highlight tip">To start creating locale groups, you must have <a href="/administration/dyspatch_roles/">Organization Administrator permission level</a></div>

## Using Locale Groups

### Adding All Locales Individually to an Email

To add all locales in the locale group as separate entries that can be localized independently from one another, go to the localizations tab in the Dyspatch Email Builder and select **Create a Localization**.

![Arrow pointing to the create a localization button in the email builder](https://docs.dyspatch.io/img/localizations/create-a-localization.png)

Select the locale group by selecting it from the dropdown menu.

![Adding a locale group to an email via a localization](https://docs.dyspatch.io/img/localizations/adding-locale-group-to-email.png)

<div class="highlight tip">
By default locale groups will appear at the top of the list and will automatically update the name to the matching locale group name.
</div>

Each locale from the group will be available under the Localizations tab.

![Multiple locales from the locale list showing the Localizations tab](https://docs.dyspatch.io/img/localizations/locales-list-in-email.png)

You can now go through the same localization process as outlined in our
[Localizing an Email](/localization/localizing_an_email/) guide.

### Adding Single Translation For Locale Group

By grouping locales that share the same language, "en-AE", "en-AU", and "en-BR" for example, you can use one translation for the entire group. This can be done through the <a href="https://docs.dyspatch.io/api/" target="_blank">Dyspatch API</a> with the locale group ID and template draft ID.

### Getting and Adding Locale Groups via API

The `localeGroup` parameter provides you an ID for any created locale groups in your account and can be used to apply
translations to a group by [adding the locale group to a draft](#add-locale-group-to-a-draft).

#### Get Draft Locale Group ID

**Request URL**

```bash
GET https://api.dyspatch.io/drafts/tdft_01dwde5bkh1znw5krbskv/localizations
```

**Response**

```json
[
  {
    "id": "loc_01dwdmm8p7n3kkvdx7dbn",
    "languages": [
        "en-AE",
        "en-AU",
        "en-BR",
        ...
    ],
    "localeGroup": "lg_01dvxt2wr1gcvkxf85a5f",
    "name": "All English Localizations",
    "updatedAt": "2024-09-06T16:45:07Z",
    "url": "https://api.dyspatch.io/localizations/loc_01dwdmm8p7n3kkvdx7dbn/drafts/tdft_01dwde5bkh1znw5krbskv"
  }
]
```

### Add Locale Group to a Draft

**Request URL**

```bash
PUT https://api.dyspatch.io/drafts/tdft_01dwde5bkh1znw5krbskv/localizations/lg_01dvxt2wr1gcvkxf85a5f
```

**Request Body**

```json
{
  "name": "All English Localizations"
}
```

**Response**

```bash
200 OK
```

#### Add Translations for Locale Group

**Request URL**

```bash
PUT https://api.dyspatch.io/drafts/tdft_01dwde5bkh1znw5krbskv/localizations/lg_01dvxt2wr1gcvkxf85a5/translations
```

**Request Body**

```json
{
  "bienvenue en %(company_brand)s": "welcome to %(company_brand)s",
  "merci pour l'enregistrement!": "thanks for signing up!"
}
```

**Response**

```bash
200 OK
```

This same translation will now be used for every locale from the locale group added through the API.

For a detailed example and walkthrough using the API, take a look here:
[Localizing using the Dyspatch API](/localization/localizing_workflow/)