# General Translation Integrations: Обработка локалей в Shopify Hydrogen
URL: https://generaltranslation.com/ru/docs/integrations/shopify/reference/locale-handling.mdx
Docs index: https://generaltranslation.com/llms.txt
Description: Как витрина на Shopify использует единую локаль для текстов витрины, содержимого каталога, URL-адресов и рынков. Справочник по обработке локалей в витринах Shopify.
Эти правила действуют для любой витрины на Hydrogen — как на React Router, так и на Next.js. Они гарантируют, что `gt-react` или `gt-next`, контекст Storefront API в Shopify, маршрутизация и кэширование работают с одной и той же локалью при каждом запросе.
## Обзор [#overview]
| Тема | Описание |
| -------------------------------------- | ------------------------------------------------------------------------------------------------ |
| [Коды локалей](#locale-codes) | Единый список локалей, явно сопоставленный с кодами Shopify. |
| [Маршрутизация](#routing) | Язык определяется по URL, и у каждой страницы один канонический URL. |
| [Язык и рынок](#language-market) | Язык контента и страна для коммерции задаются независимо, и их можно сочетать для каждой локали. |
| [Кэшированные страницы](#cached-pages) | Переводы поставляются вместе со сборкой. |
## Коды локалей [#locale-codes]
Определяйте локали один раз — в `gt.config.json`. Маршрутизацию, ``, провайдер, переключатель языка и контекст запросов к Shopify формируйте на основе этого списка, а не ведите второй.
В витрине Shopify у каждого языка есть три кода:
* **Локали General Translation** — это теги BCP 47, например `fr` или `pt-BR`. (См. [Коды локалей](/docs/platform/core/guides/locale-codes).)
* **Значения `LanguageCode` в Storefront API** — это перечисления в верхнем регистре с символами подчеркивания, например `FR` или `PT_BR`. Передавайте их в `@inContext(language:)`.
* **Локали Admin API** — это коды локалей магазина, например `fr` или `pt-BR`. Передавайте их в `translationsRegister`.
Задавайте сопоставление для каждой локали явно. Замена `_` на `-` подходит для большинства кодов, но не для всех:
| Shopify `LanguageCode` | Язык | Локаль General Translation |
| ---------------------- | -------------------------- | -------------------------- |
| `EN` | Английский | `en` |
| `FR` | Французский | `fr` |
| `JA` | Японский | `ja` |
| `PT_BR` | Португальский (Бразилия) | `pt-BR` |
| `PT_PT` | Португальский (Португалия) | `pt-PT` |
| `ZH_CN` | Китайский (упрощённый) | `zh-CN` или `zh-Hans` |
| `ZH_TW` | Китайский (традиционный) | `zh-TW` или `zh-Hant` |
`ZH_CN` и `ZH_TW` обозначают не только регион, но и письменность. При этом `zh-TW` подразумевает ещё и Тайвань, а `zh-Hant` означает традиционный китайский в любом регионе. Выберите для каждого языка Shopify одну локаль и используйте её в `gt.config.json`, URL и ``.
**Скоро в Hydrogen:** в открытых пул-реквестах предлагаются вспомогательные функции для работы с локалями. [Shopify/hydrogen#4009](https://github.com/Shopify/hydrogen/pull/4009) добавляет `defineShopifyI18n` — определение локалей с маршрутизацией по пути или домену — и вспомогательные функции, например `getSupportedLocales`. [Shopify/hydrogen#4325](https://github.com/Shopify/hydrogen/pull/4325) добавляет `getHtmlLang`, которая преобразует `LanguageCode` в корректный тег ``: например, `PT_BR` в `pt-BR`, а `ZH_TW` в `zh-Hant`. Ни одно из этих изменений пока не вошло в релиз `@shopify/hydrogen`, поэтому ведите собственный список локалей и сопоставление.
Формируйте теги только по языку. Покупатель на канадском рынке, выбравший французский, получает `fr`, а не `fr-CA`. Добавляйте отдельную локаль, например `fr-CA`, только если ведёте для неё отдельные тексты.
## Маршрутизация [#routing]
### Язык определяется URL
Разрешайте локаль по пути запроса или домену и передавайте одно и то же значение в провайдер, `` и контекст запросов Shopify. Cookie-файл или `Accept-Language` могут подсказать, куда выполнить перенаправление, но один и тот же URL всегда рендерится на одном языке, поэтому кэши и поисковые системы видят для каждого URL ровно один язык.
### Один канонический URL для каждой страницы
Отдавайте локаль по умолчанию без префикса, а остальные локали — с префиксом, например `/fr/products/hoodie`. Для локали по умолчанию с префиксом (например, `/en/products/hoodie`) и для неизвестных префиксов возвращайте 404. Ссылки, отрисованные на локализованной странице, сохраняют её префикс.
Передайте префикс в Hydrogen через `i18n.pathPrefix` в `createShopifyRequestContext`, например `/fr`, или пустую строку для локали по умолчанию. Hydrogen добавляет его к возвращаемым перенаправлениям для вариантов товаров и стандартных маршрутов.
### Нелокализованные маршруты
Маршруты, которые Shopify или его скрипты вызывают по фиксированным путям, оставляйте без префикса: обработчики API корзины и предиктивного поиска, функции обратного вызова для авторизации в аккаунте клиента и прочие маршруты `/api`. В шаблоне Vercel Shop файл `proxy.ts` передаёт эти запросы функции `handleShopifyRoutes` из Hydrogen ещё до какой-либо перезаписи по локали. (См. [Локализация витрины Shopify на Next.js](/docs/integrations/shopify/guides/localizing-nextjs#routing)).
При этом запросам корзины и предиктивного поиска по-прежнему нужен язык страницы, иначе Shopify вернёт текст каталога на языке по умолчанию. Сохраняйте локаль страницы в cookie-файле, считывайте её только для этих запросов без префикса и принимайте лишь настроенные локали. (См. [Сохранение языка страницы в обработчиках Hydrogen](/docs/integrations/shopify/guides/localizing-react-router#handler-locale)).
## Язык и рынок [#language-market]
Директива `@inContext` в Storefront API принимает параметры `language` и `country`. Они отвечают за разное:
* **`language`** определяет, на каком языке Shopify вернёт содержимое каталога. Это значение соответствует локали страницы.
* **`country`** определяет рынок, от которого зависят цены, валюта и доступность товаров. Для корзины этот параметр действует только до тех пор, пока у корзины нет данных покупателя, и сам их никогда не задаёт. Задайте страну покупателя через `cartCreate` или `cartBuyerIdentityUpdate`; после этого данные покупателя имеют приоритет над конфликтующими значениями `@inContext`. (См. [правила контекста корзины](https://shopify.dev/docs/storefronts/headless/building-with-the-storefront-api/in-context#cart-queries-and-mutations) в документации Shopify).
Выберите, как связать эти параметры:
* **Один рынок для всех языков.** Передавайте одну и ту же страну для всех локалей. Смена языка меняет только тексты интерфейса и каталога, но не затрагивает цены и корзину.
* **Отдельный рынок для каждого языка.** Сопоставьте каждой локали страну, например французскому — Францию, а японскому — Японию, и передавайте эту страну вместе с языком локали. Тогда для каждого языка будут отображаться цены и валюта соответствующего рынка. При смене языка обновляйте `countryCode` покупателя в корзине с помощью `cartBuyerIdentityUpdate`, поскольку валюта корзины определяется страной покупателя. (См. [Продажи на нескольких рынках](/docs/integrations/shopify/guides/selling-in-markets)).
Чтобы покупатели могли выбирать страну независимо от языка, добавьте вместо этого отдельный переключатель страны и обновляйте данные покупателя при каждом её изменении.
Никогда не конвертируйте цены и не определяйте валюту по локали. Форматируйте суммы из Shopify с кодом валюты, который возвращает Shopify, с помощью [``](/docs/react/reference/components/currency) или `formatMoney` из Hydrogen.
## Кэшированные страницы [#cached-pages]
Если страницы кэшируются или предварительно рендерятся, загружайте переводы из файлов, включённых в бандл при сборке. Запросы перевода во время выполнения не могут выполняться внутри статической оболочки. В Next.js с Cache Components необходима пользовательская функция [`loadTranslations`](/docs/react/reference/functions/load-translations) (см. [Использование Cache Components](/docs/react/nextjs/cache-components)).
Переводы каталога, хранящиеся в Shopify, не входят в сборку: для них действуют настройки кэширования вашего Storefront API.
## Sitemap
See the full [sitemap](https://generaltranslation.com/sitemap.md) for all pages.