Add Localization doc (#741)

* create new localization md file

* add content for localization doc

* update localization file to include references to next.js internationalization

* Update localization.md

* Update localization.md

* Update localization.md

---------

Co-authored-by: Volodymyr Krasnoshapka <88093058+BC-krasnoshapka@users.noreply.github.com>

docs/localization.md

@@ -0,0 +1,148 @@
+# Localization 
+
+You can localize your Catalyst storefront so that it appears in the shopper's preferred language throughout browsing and checkout experience.
+This provides a personalized shopping experience when you sell products internationally. 
+
+> [!Note]
+> - Internationalization support in Catalyst is WIP. Full multi-lingual support in headless channels, like Catalyst, will be added in future releases.
+> - Currently each Catalyst storefront can only support a single language. To display multiple languages, we recommend setting up a separate channel for each language.
+> - To fully localize a store for a language or region, you will need to customize product catalog and storefront content in the BigCommerce control panel.
+
+Catalyst uses [Next.js App Router Internationalization (i18n)](https://next-intl-docs.vercel.app/docs/getting-started/app-router) library to handle localization.
+
+This guide describes how to provide static string translations for shoppers, including the required subdirectory, file structure and project configuration. 
+
+## Required subdirectory
+
+Each Catalyst project reserves a top level `/messages/` subdirectory for localization.
+For your storefront to function properly, both the `/messages/` subdirectory and the `/messages/en.json` file, which contains the default English phrases, must be present.
+You can localize static phrases by providing other JSON translation files in the `/messages/` directory. 
+
+> [!Note]
+> #### Default language
+> Catalyst hardcodes the `en.json` file as the default language file, which contains U.S. English translations when you set up the project [using the CLI](https://www.catalyst.dev/docs/cli). You can adjust default phrases to your needs if desired.
+
+## Translation file
+
+To translate static phrases, create a JSON file for each language you choose to support. Each language that you want to support must have its own JSON file.
+
+Name your translation files based on the [BCP 47 specification](https://tools.ietf.org/html/bcp47) of language tags and region codes. For an overview of how these language tags are constructed, see [Language tags in HTML and XML](http://www.w3.org/International/articles/language-tags/).
+
+You can find a list of code subtags in the [IANA Language Subtag Registry](http://www.iana.org/assignments/language-subtag-registry). These subtags are primitives that you can combine to create file name prefixes for individual regions. Here are some examples:
+
+| Localization file name | Corresponding regional language variant | Subtags used |
+| ----------- | ----------- | ----------- |
+| `en.json` | English (default file)| en (English) |
+| `en-US.json` | American English | en (English) + US (United States) |
+| `en-AU.json` | Australian English | en (English) + AU (Australia) |
+| `fr.json` | French | en (French) |
+| `fr-CA.json` | Canadian French | fr (French) + CA (Canada) |
+
+### Translation keys
+
+The JSON files should contain key-value pairs for each locale. You can define translations based on a pre-defined keys used to translate the Catalyst storefront's [basic ecommerce functionality](https://www.catalyst.dev/docs#ecommerce-functionality). The translated values you specify will display to shoppers as static string translations.
+
+Use the existing `en.json` file as a template for the schema.
+You can only provide translated values for the translation keys specified in the template. 
+
+For example, the `en.json` file contains translation keys for 
+
+```json
+"Home": {
+  "Carousel": {
+    "bestSellingProducts": "Best Selling Products",
+    "featuredProducts": "Featured Products",
+    "newestProducts": "Newest products"
+  }
+}
+``` 
+
+In your newly-created JSON file, add a translation of the value to the new locale
+
+```json
+"Home": {
+  "Carousel": {
+    "bestSellingProducts": "Produits les plus vendus",
+    "featuredProducts": "Produits populaires",
+    "newestProducts": "Produits les plus recentsProduits"
+  }
+}
+``` 
+
+Read more about i18n messages in [next-intl docs](https://next-intl-docs.vercel.app/docs/usage/messages).
+
+## i18n configuration
+
+After you created a language file, add its name to the `i18n.ts` config file.
+
+For example, if you created a `fr.json` file, include the `fr` when you define the locales:   
+
+```ts
+const locales = ['en', 'fr'] as const;
+```
+
+## Using keys in React components
+
+The following example shows how messages can be used in **server** component:
+
+```tsx
+import { NextIntlClientProvider } from 'next-intl';
+import { getMessages, getTranslations, unstable_setRequestLocale } from 'next-intl/server';
+// ...
+import { LocaleType } from '~/i18n';
+
+interface Props {
+  params: {
+    locale: LocaleType;
+  };
+}
+
+export default async function Home({ params: { locale } }: Props) {
+  unstable_setRequestLocale(locale);
+
+  const t = await getTranslations({ locale, namespace: 'Home' });
+  const messages = await getMessages({ locale });
+  // ...
+
+  return (
+    <div>
+      <NextIntlClientProvider locale={locale} messages={{ Product: messages.Product ?? {} }}>
+        <ProductCardCarousel
+          products={featuredProducts}
+          title={t('Carousel.featuredProducts')}
+        />
+      </NextIntlClientProvider>
+    </div>
+  );
+}
+```
+
+> [!Note]
+> #### unstable_setRequestLocale
+> Please pay attention to `unstable_setRequestLocale` call. You can read more in [next-intl docs](https://next-intl-docs.vercel.app/docs/getting-started/app-router#add-unstable_setrequestlocale-to-all-layouts-and-pages).
+
+Usage in nested **client** component:
+```tsx
+'use client';
+
+// ...
+import { useTranslations } from 'next-intl';
+
+export const AddToCart = () => {
+  const t = useTranslations('Product.ProductSheet');
+
+  return (
+    <Button type="submit">
+        t('addToCart')
+    </Button>
+  );
+};
+```
+
+## Routing and locale detection
+
+Even though next-intl library supports several [locale detection strategies](https://next-intl-docs.vercel.app/docs/routing/middleware#strategies), at the moment Catalyst doesn't use any by default as full internationalization support is in progress. Strategy can be changed in `i18n.ts` config file.
+
+Currently storefront locale is detected by shopper's browser preferences by default.
+Catalyst uses the `Accept-Language` request HTTP header to determine which translation file to chose. 
+Default English file will be used if you do not have a JSON file matching the shopper's browser language.