# Localization

Project Zero Next supports multiple languages and currencies, and all the necessary settings for language and currency management can be found within the settings.js file.

## <mark style="color:red;">Locales</mark>​ <a href="#locales" id="locales"></a>

### <mark style="color:red;">Adding a New Locale​</mark> <a href="#adding-a-new-locale" id="adding-a-new-locale"></a>

To add a new locale to the project, follow these steps:

1. Open the settings.js file.
2. Locate the **localization** section.
3. Inside the **locales** array, add a new object with the following properties:

<table><thead><tr><th width="222.9921875">Property</th><th>Description</th></tr></thead><tbody><tr><td>label</td><td>A label that can be displayed on any page of the website.</td></tr><tr><td>value</td><td>The lowercase locale value in ISO 639-1 format or including the country code in ISO 3166-1 alpha-2 format.</td></tr><tr><td>localePath</td><td>Name of the locale's JSON translation file. For example, if the value is "en," the file should be placed in the public/locales/en directory.</td></tr><tr><td>apiValue</td><td>The value of the locale defined in Commerce.</td></tr><tr><td>rtl</td><td>A boolean value that specifies whether it is right-to-left, like Arabic.</td></tr></tbody></table>

Here's an example of adding a new locale:

```
localization: {
  locales: [
    {
      label: 'EN',
      value: 'en',
      localePath: 'en',
      apiValue: 'en-us',
      rtl: false,
    },
  ],
}
```

### <mark style="color:red;">Default Locale​</mark> <a href="#default-locale" id="default-locale"></a>

The default locale for the project can be specified by using the **defaultLocaleValue** in the settings.js file. This value should match the "value" of one of the defined locales.

### <mark style="color:red;">Setting a Locale​</mark> <a href="#setting-a-locale" id="setting-a-locale"></a>

To set a locale in the project, the **setLocale** method available in the useLocalization hook can be used. This method will automatically change the URL to reflect the selected locale.

Example of using **setLocale**:

```
const { setLocale } = useLocalization();

setLocale('en-us');
```

### <mark style="color:red;">Disabling Redirection to Default Locale​</mark> <a href="#disabling-redirection-to-default-locale" id="disabling-redirection-to-default-locale"></a>

In some cases, like displaying a landing page on example.com/ while using the ShowAllLocales strategy, users are automatically redirected to URLs containing the default locale (e.g., example.com/en). To disable this redirection, set **redirectToDefaultLocale** to false in the settings.js file:

```
localization: {
  redirectToDefaultLocale: false,
}
```

## <mark style="color:red;">Currencies</mark>​ <a href="#currencies" id="currencies"></a>

### <mark style="color:red;">Adding a New Currency​</mark> <a href="#adding-a-new-currency" id="adding-a-new-currency"></a>

To add a new currency to the project, follow these steps:

1. Open the settings.js file.
2. Locate the **currencies** section.
3. Inside the **currencies** array, add a new object with the following properties:
   * **label**: The label for the currency (e.g., 'USD').
   * **code**: The code for the currency (e.g., 'usd').

Here's an example of adding a new currency:

```
currencies: [
  {
    label: 'USD',
    code: 'usd',
  },
]
```

### <mark style="color:red;">Default Currency​</mark> <a href="#default-currency" id="default-currency"></a>

The default currency in the project can be specified by using the **defaultCurrencyCode** in the settings.js file. This code must match the "code" of one of the defined currencies.

### <mark style="color:red;">Determining Active Currency​</mark> <a href="#determining-active-currency" id="determining-active-currency"></a>

The **getActiveCurrencyCode** function's default behavior is to retrieve the active currency code from a cookie named `pz-currency`. Users can customize this function to obtain the currency code from different sources, such as headers or the URL. If the return value doesn't match any currency code in the `currencies` array, the default currency code will be used.

Here's an example:

```
getActiveCurrencyCode: ({ req, locale, defaultCurrencyCode }) => {
  const [, countryCode] = locale.split('-');

  if (countryCode === 'ae') {
    return 'aed';
  } else if (countryCode === 'qa') {
    return 'qar';
  }

  return defaultCurrencyCode;
}
```

## <mark style="color:red;">URL Strategy​</mark> <a href="#url-strategy" id="url-strategy"></a>

Project Zero Next supports multiple URL structures to cater to different requirements. Users can set the URL strategy using the **localeUrlStrategy** value in settings.js.

Example of setting the URL strategy:

```
localization: {
  localeUrlStrategy: LocaleUrlStrategy.ShowAllLocales,
}
```

The available values for **localeUrlStrategy** are:

* LocaleUrlStrategy.HideDefaultLocale
* LocaleUrlStrategy.HideAllLocales
* LocaleUrlStrategy.ShowAllLocales

LocaleUrlStrategy.HideDefaultLocale:

* For English (en): "/women"
* For Turkish (tr): "/tr/women"

LocaleUrlStrategy.ShowAllLocales:

* For English (en): "/en/women"
* For Turkish (tr): "/tr/women"

LocaleUrlStrategy.HideAllLocales:

* For English (en): "/women"
* For Turkish (tr): "/women"

{% hint style="info" %}
The "HideAllLocales" option is not recommended for SEO purposes.
{% endhint %}

## <mark style="color:red;">Translations</mark>​ <a href="#translations" id="translations"></a>

Translations can be managed by adding key-value pairs to JSON files located under the public/locales directory. For example, if the English (en) locale is used, translation files can be stored in public/locales/en/account.json.

## <mark style="color:red;">Localization in Components​</mark> <a href="#localization-in-components" id="localization-in-components"></a>

### <mark style="color:red;">Client Components​</mark> <a href="#client-components" id="client-components"></a>

The **useLocalization** hook provides all the necessary properties for localization in client components. To make use of translations in the client components, use the "**t**" function as shown in the example below:

```
import { useLocalization } from '@akinon/next/hooks';

const {
  t,
  currencies,
  currency,
  defaultCurrencyCode,
  locales,
  locale,
  defaultLocaleValue,
  localeUrlStrategy,
  setLocale,
} = useLocalization();

const translatedText = t('account.change_email.header.title');
```

### <mark style="color:red;">Server Components​</mark> <a href="#server-components" id="server-components"></a>

For server components, the "**t**" function can be imported from the following path to access translations:

```
import { t } from '@akinon/next/utils/server-translation';

const translatedText = t('account.change_email.header.title');
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.akinon.com/technical-guides/project-zero/next.js/plugins/akinon-next/localization.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.