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.

Locales

Adding a New Locale

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:

Property	Description
label	A label that can be displayed on any page of the website.
value	The lowercase locale value in ISO 639-1 format or including the country code in ISO 3166-1 alpha-2 format.
localePath	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.
apiValue	The value of the locale defined in Commerce.
rtl	A boolean value that specifies whether it is right-to-left, like Arabic.

Here's an example of adding a new locale:

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

Default Locale

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.

Setting a Locale

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

Disabling Redirection to Default Locale

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,
}

Currencies

Adding a New Currency

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',
  },
]

Default Currency

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.

Determining Active Currency

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;
}

URL Strategy

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"

Note: The "HideAllLocales" option is not recommended for SEO purposes.

Translations

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.

Localization in Components

Client Components

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

Server Components

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