-
Notifications
You must be signed in to change notification settings - Fork 100
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* 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 <[email protected]>
- Loading branch information
1 parent
301b775
commit bfde483
Showing
1 changed file
with
148 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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. |