# 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');
```