# About the Locales API

The Multilingual Locales API allows you to manage a site's locales. By supporting multiple locales, a site can cater to different languages and regions, helping Wix users reach a global audience.

With the Locales API, you can:

- Create, update, and delete locales for a site.
- Retrieve and query locales.
- Change a site's primary locale. 
- Retrieve a list of locales supported by Wix.

To retrieve or update a site's locale settings, or enable multilingual mode, refer to the [Locale Settings API](fallback::https://dev.wix.com/docs/api-reference/business-management/multilingual/locale-management/locale-settings/introduction). 

## Before you begin

It's important to note the following points before starting to code:

- The Wix user must install the [Wix Multilingual app](fallback::https://www.wix.com/app-market/wix-multilingual?searchLocation=home) on their site. 
- Create, update and delete methods can only be called on sites where [multilingual mode](fallback::https://dev.wix.com/docs/api-reference/business-management/multilingual/locale-management/locale-settings/set-multilingual-mode) is enabled. 
- You can't change a primary locale to a secondary locale that already exists on a site. You must first delete the secondary locale and then call Create New Primary Locale. 
- A site can have up to 200 locales and up to 100 visible locales.

## Use cases

- [Implement a custom language switcher](fallback::https://dev.wix.com/docs/api-reference/business-management/multilingual/locale-management/locales/sample-flows#implement-a-custom-language-switcher).
- [Change the primary locale of a site](fallback::https://dev.wix.com/docs/api-reference/business-management/multilingual/locale-management/locales/sample-flows#change-primary-locale).

## Terminology

- **Locale**: A combination of the language and optional region code that defines how content should be displayed for a specific audience.
- **Primary locale**: The locale in which the site is created, serving as the default language and regional settings. This locale serves as the base for translating to other locales. 
- **Visitor primary locale**: The default language shown to site visitors when they first visit the site and no language is specified in the site's URL. 
- **Secondary locale**: A locale on your site that is used to display translated content or localized versions on the site based on visitor preferences. 
- **Visibility**: The status of a locale. 
    - **Visible**: Visible locales are visible to site visitors, meaning visitors can view the site in that locale. 
    - **Hidden**: Hidden locales can't be accessed by site visitors, but are available to Wix users for translating content in that locale.  




@sdk_package_setup

# Locales: Sample Flows

This article presents some possible use cases you can support using the Locale API. This can be a helpful jumping off point as you plan your implementation.


## Implement a custom language switcher

You can create a custom language switcher presented as a dropdown of available languages or regions for site visitors to select from.

1. Call [Query Locales](fallback::https://dev.wix.com/docs/api-reference/business-management/multilingual/locale-management/locales/query-locales) with `{ "visibility": "VISIBLE" }` to retrieve a list of all visible locales for the site.

1. Display the retrieved locales in your custom language switcher, showing each locale's `displayName` and `flag`.

1. When a site visitor selects a different language, use the locale's `id` and `effectiveUrlStructure` to construct the appropriate URL for the newly selected language version of the current page, and then redirect the visitor to that URL.

## Change primary locale 

You can change the site's primary locale, for example if headquarters relocates to a different country.

1. Call [List Supported Locales](fallback::https://dev.wix.com/docs/api-reference/business-management/multilingual/locale-management/locales/list-supported-locales) to see a list of all locales supported by Wix.

1. Choose a locale from the list and call [Get Locale](fallback::https://dev.wix.com/docs/api-reference/business-management/multilingual/locale-management/locales/get-locale) to ensure the locale doesn't already exist on the site as a secondary locale. 

    If the locale already exists on the site, call [Delete Locale](fallback::https://dev.wix.com/docs/api-reference/business-management/multilingual/locale-management/locales/delete-locale) to remove it and its data. 

2. Call [Create New Primary Locale](fallback::https://dev.wix.com/docs/api-reference/business-management/multilingual/locale-management/locales/create-new-primary-locale) to create and set the new primary locale. 

3. Call [Get New Primary Locale Status](fallback::https://dev.wix.com/docs/api-reference/business-management/multilingual/locale-management/locales/get-new-primary-locale-status) with the token returned from the Create New Primary Locale method and monitor the progress of the change, and continue checking the status until the it returns either `FINISH_SUCCESSFUL` or
   `FINISH_WITH_ERROR`.

4. If the change is successful, update your app's UI to reflect the new primary locale. If there's an error, inform the Wix user and provide options for troubleshooting or retrying the operation.

# Locale API: Errors

This table outlines errors that might be issued when calling the Locale API. The list includes error codes,
and troubleshooting guidance to help you resolve these issues.

| <div style="width:200px">HTTP STATUS</div> | <div style="width:300px">ERROR NAME</div> | <div style="width:300px">RULE NAME</div>  | <div style="width:200px">DESCRIPTION & TROUBLESHOOTING</div>                                                 |
| :----------------------------------------- | :---------------------------------------- | :---------------------------------------- | :----------------------------------------------------------------------------------------------------------- |
| `BAD_REQUEST (400)`                        | `InvalidArgumentException`                | `MaxLocaleCountRule`                      | Exceeded 200 locale per site limit. Delete unused locales.                                  |
| `BAD_REQUEST (400)`                        | `InvalidArgumentException`                | `MaxVisibleLocaleCountRule`               | A site can only have up to 100 visible locales. Hide or remove locales.                         |
| `BAD_REQUEST (400)`                        | `InvalidArgumentException`                | `MultilingualModeMustBeEnabledRule`       | Multilingual mode must be enabled. Enable multilingual mode in site settings.                                |
| `BAD_REQUEST (400)`                        | `InvalidArgumentException`                | `NoPrimaryLocaleRule`                     | A site can only have one primary locale. Remove primary locale flag from additional locales.                 |
| `BAD_REQUEST (400)`                        | `InvalidArgumentException`                | `NoVisitorPrimaryLocaleRule`              | A site can only have one visitor primary locale. Remove visitor primary locale flag from additional locales. |
| `BAD_REQUEST (400)`                        | `InvalidArgumentException`                | `ValidFlagCodeRule`                       | Unrecognized flag code. Use a valid country code for the flag.                                               |
| `BAD_REQUEST (400)`                        | `InvalidArgumentException`                | `ValidLanguageAndRegionRule`              | Unrecognized language and region combination. Use a valid language-region code combination.                  |
| `BAD_REQUEST (400)`                        | `InvalidArgumentException`                | `ValidMachineTranslationCode`             | Unsupported machine translation code. Use a supported machine translation language code.                     |
| `BAD_REQUEST (400)`                        | `InvalidArgumentException`                | `VisitorPrimaryLocaleMustBeVisibleRule`   | The visibility status of a locale with `visitorPrimaryLocal` set to `true` must be `VISIBLE`. Update the `visibility` field to VISIBLE for the visitor primary locale.    |
| `BAD_REQUEST (400)`                        | `InvalidArgumentException`                | `PrimaryLocaleIsVisitorPrimaryLocaleRule` | The primary locale must also be set as the visitor primary locale. Ensure the primary locale's `visitorPrimaryLocale` is set to `true`.   |
| `BAD_REQUEST (400)`                        | `UnexpectedValueException`                |                                        | Unexpected value occurred. Check the provided value matches expected format.                                 |

Multilingual Primary Locale Changed