docs: add localization overview & guide (#1332)

* docs: add localization overview & guide

* fix: update file name

* fix: remove duplicate example

---------

Co-authored-by: Jorge Moya <jorge.moya@bigcommerce.com>

docs/internationalization.md

@@ -0,0 +1,30 @@
+# Internationalization
+
+You can localize your Catalyst storefront so that it appears in the shopper's preferred culture or language throughout their browsing and checkout experience. 
+
+> [!NOTE] 
+> Internationalization support in Catalyst is a work in progress. Full multilingual support in headless channels, like Catalyst, will be added in future releases.
+
+## Use cases
+
+Catalyst supports the following scenarios:
+
+1. You are selling internationally and would like to tailor your storefront to multiple countries. Each country has its own language, currency, payment method, etc.
+
+2. You are selling within a country would like to accommodate multiple languages within that country
+
+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.
+
+## Locale-specific URLs
+
+Catalyst supports the following locale-specific URLs that you can use to localize your storefronts. Learn more about the pro and cons for each [locale-specific URL](https://developers.google.com/search/docs/specialty/international/managing-multi-regional-sites#locale-specific-urls) in the Google Documentation.
+
+Each Catalyst storefront can support one language per channel. However, Catalyst can service multiple languages by connecting multiple channels to the storefront and routing each language through different subpaths. To display multiple languages, we recommend setting up a separate channel for each lanuage.
+
+| URL structure | Example | Recommended use case | How to implement for Catalyst | 
+| :-- | :-- | :-- | :-- | 
+| Root domain <br /><br /> Subdomain <br /><br /> gTLD | `store.com` <br /><br /> `fr.store.com` <br /><br /> `store.co.uk` | International selling, where you want to personlize the language, currency, payment method, and more. | Create a [storefront channel](/docs/storefront/multi-storefront) and point it to a domain, subdomain, or gTLD. |
+| Domain subpath | `store.com/fr` | Providing multiple languages within a country. | The subpath can point to a different channel. |
+
+
+For best practices on how to set up localized websites, see the [Managing multi-regional and multilingual sites](https://developers.google.com/search/docs/specialty/international/managing-multi-regional-sites) guide in the Google Documentation.

docs/localization.md

@@ -1,17 +1,9 @@
 # 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 a work in progress. Full multilingual 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.
+This guide describes how to provide static string translations for shoppers, including the required subdirectory, file structure, and project configuration.
 
 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.
@@ -72,14 +64,26 @@ Read more about i18n messages in [next-intl docs](https://next-intl-docs.vercel.
 
 ## i18n configuration
 
-After you created a language file, add its name to the `i18n.ts` config file.
+After you created a language file, add its name to the `routing.ts` config file.
 
 For example, if you created a `fr.json` file, include `fr` when you define the locales:
 
 ```ts
 const locales = ['en', 'fr'] as const;
 ```
 
+## Subpath configuration (optional)
+
+If you are using domain subpaths to localize your storefront for a specific language, map the subpath to a channel in the `channels.config.ts` file.
+
+For example, if you want the `/fr` subpath to point a channel ID of `12345`, include the following:
+
+```ts
+const localeToChannelsMappings: Partial<RecordFromLocales> = {
+  fr: '12345',
+};
+```
+
 ## Using keys in React components
 
 The following example shows how messages can be used in **server** component:
@@ -127,25 +131,6 @@ const Component = () => {
 > **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).
 
-The following example shows usage in a 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 the next-intl library supports several [locale detection strategies](https://next-intl-docs.vercel.app/docs/routing/middleware#strategies), Catalyst doesn't use any by default, as full internationalization support is still in progress. This strategy can be changed in the `i18n.ts` config file.