diff --git a/docs/store-operations/translations/index.mdx b/docs/store-operations/translations/index.mdx index 639aaf989..2ea508719 100644 --- a/docs/store-operations/translations/index.mdx +++ b/docs/store-operations/translations/index.mdx @@ -1,24 +1,26 @@ # Translations Admin GraphQL API (Beta) - -The Translations Admin GraphQL API is currently available on Catalyst storefronts only. This API enables merchants to translate a single website into multiple languages. +The Translations Admin GraphQL API is currently available on Catalyst storefronts only. This API enables merchants to translate a single website into multiple languages. With a single storefront setup, the shopper's experience remains consistent, but the content is displayed in their preferred language. This use case is particularly common in multilingual countries like Canada and for customers selling cross-border, where the same storefront serves shoppers in multiple languages without altering the overall user experience. The API currently supports translations for the following resource types, and more are expected in the future: -* [Product Data](/docs/store-operations/translations/products) - * Product Options - * Custom Fields -* [Catalog Pages](/docs/store-operations/translations/listings) - * Categories - * Brands -* [Locations](/docs/store-operations/translations/locations) +- [Product Data](/docs/store-operations/translations/products) + - Product Options + - Custom Fields +- [Catalog Pages](/docs/store-operations/translations/listings) + - Categories + - Brands +- [Locations](/docs/store-operations/translations/locations) +- [Payment Methods](/docs/store-operations/translations/payments) Refer to the [Error Handling](/docs/store-operations/translations/errors) guide for understanding and handling errors while managing translations. - -Translation API allows users to add content translations to any non-default channel locale. In order to update content on a default channel language, please use respective management API. + + Translation API allows users to add content translations to any non-default + channel locale. In order to update content on a default channel language, + please use respective management API. ## How does this API work? @@ -38,10 +40,10 @@ Access to the Translations Admin GraphQL API requires valid API credentials. Gra #### OAuth scopes -| Name | Permission | Description | -|:-----|:-----------|:------------| -| Store Translations | read-only | View translation details | -| Store Translations | modify | View and modify translation details | +| Name | Permission | Description | +| :----------------- | :--------- | :---------------------------------- | +| Store Translations | read-only | View translation details | +| Store Translations | modify | View and modify translation details | For more information on OAuth Scopes, see our [Guide to API Accounts](/docs/start/authentication/api-accounts#oauth-scopes). @@ -71,4 +73,5 @@ For more information on OAuth Scopes, see our [Guide to API Accounts](/docs/star - [Product Translations](/docs/store-operations/translations/products) - [Catalog Page Translations](/docs/store-operations/translations/listings) - [Inventory Locations Translations](/docs/store-operations/translations/locations) +- [Payment Method Translations](/docs/store-operations/translations/payments) - [Error Handling Reference](/docs/store-operations/translations/errors) diff --git a/docs/store-operations/translations/payments.mdx b/docs/store-operations/translations/payments.mdx new file mode 100644 index 000000000..eb5c198bd --- /dev/null +++ b/docs/store-operations/translations/payments.mdx @@ -0,0 +1,305 @@ +# Translations for Payments (Beta) + +The following entities are translatable for payments: + +- Display Name as `display_name` +- Payment Instruction as `payment_instruction` + +Translations appear in the following storefront views: + +- Checkout page (payment methods listing) +- Order confirmation page +- Order email +- My Account page (payment methods and orders) + +## Resource fields + +For payment method related translation entries, the `resourceId` follows this structure: + +`bc/store/paymentMethod/{payment_method_id}.{currency}` + +| **Segment** | **Description** | +| ------------------------ | -------------------------------------------------------------------- | +| `bc/store/paymentMethod` | Namespace prefix for payment translation resources. | +| `{payment_method_id}` | Payment method identifier (e.g., `authorizenet.credit_card`). | +| `{currency}` | The ISO currency code configured for the payment method (e.g `USD`). | + +A single `resourceId` corresponds to all payment profiles that share the same payment method ID and currency. As a result: + +- Translations apply at the payment method \+ currency level. +- If a provider has multiple profiles (e.g., multiple gateway configurations) using the same payment method ID and same currency, they share the same translation resource. +- Updating the translation updates the display for every profile in that set. + +### Example + +In this example, the payment method is `authorizenet.credit_card` and the currency is `USD`. The translation will be applied to all payment profiles that use the same payment method ID and currency. + +`"resourceId": "bc/store/paymentMethod/authorizenet.credit_card.USD"` + +## Querying Payment Method Translations + +This query retrieves all payment method translations for a specific channel and locale, including the original and translated values for display names and payment instructions. + + + +```graphql +query ListPaymentMethodTranslations { + store { + translations( + filters: { + resourceType: PAYMENT_METHODS + channelId: "bc/store/channel/1" + localeId: "bc/store/locale/en-AU" + } + ) { + edges { + node { + resourceId + fields { + fieldName + original + translation + } + } + cursor + } + pageInfo { + hasNextPage + hasPreviousPage + startCursor + endCursor + } + } + } +} +``` + + +```json +{ + "data": { + "store": { + "translations": { + "edges": [ + { + "node": { + "resourceId": "bc/store/paymentMethod/authorizenet.credit_card.USD", + "fields": [ + { + "fieldName": "display_name", + "original": "Authorize.Net", + "translation": null + }, + { + "fieldName": "payment_instruction", + "original": "", + "translation": null + } + ] + }, + "cursor": "YXV0aG9yaXplbmV0LmNyZWRpdF9jYXJkLlVTRA" + } + ], + "pageInfo": { + "hasNextPage": false, + "hasPreviousPage": false, + "startCursor": "YXV0aG9yaXplbmV0LmNyZWRpdF9jYXJkLlVTRA", + "endCursor": "YXV0aG9yaXplbmV0LmNyZWRpdF9jYXJkLlVTRA" + } + } + } + } +} +``` + + + +## Querying Payment Method Translations by resourceId + + +When querying a translation by `resourceId`, you must provide the full `resourceId` in the format `bc/store/paymentMethod/{payment_method_id}.{currency}`. + + +This query returns a translation by `resourceId`. + + + +```graphql +query { + store { + translations( + filters: { + resourceType: PAYMENT_METHODS + channelId: "bc/store/channel/1" + localeId: "bc/store/locale/en" + resourceIds: [ + "bc/store/paymentMethod/authorizenet.credit_card.USD" + ] + } + ) { + edges { + node { + resourceId + fields { + fieldName + original + translation + } + } + cursor + } + } + } +} +``` + + +```json +{ + "data": { + "store": { + "translations": { + "edges": [ + { + "node": { + "resourceId": "bc/store/paymentMethod/authorizenet.credit_card.USD", + "fields": [ + { + "fieldName": "display_name", + "original": "Authorize.Net", + "translation": null + }, + { + "fieldName": "payment_instruction", + "original": "", + "translation": null + } + ] + }, + "cursor": "YXV0aG9yaXplbmV0LmNyZWRpdF9jYXJkLlVTRA" + } + ] + } + } + } +} +``` + + + +## Update a Payment Method Translation + +This mutation updates the translated values for payment method display names and payment instructions for a specific payment method, channel, and locale. + + + +```graphql +mutation UpdatePaymentMethodTranslations { + translation { + updateTranslations( + input: { + resourceType: PAYMENT_METHODS + channelId: "bc/store/channel/1" + localeId: "bc/store/locale/en-AU" + entities: [ + { + resourceId: "bc/store/paymentMethod/authorizenet.credit_card.USD" + fields: [ + { fieldName: "display_name", value: "Translated display" } + { fieldName: "payment_instruction", value: "Translated instrumention" } + ] + } + ] + } + ) { + errors { + __typename + ... on ValidationError { + message + } + ... on EntityNotFoundError { + id + message + } + ... on InvalidTranslationEntityFieldsError { + id + message + fields + } + } + } + } +} +``` + + +```json +{ + "data": { + "translation": { + "updateTranslations": { + "errors": [] + } + } + } +} +``` + + + +## Delete a Payment Method Translation + +This mutation removes translated values for specified payment method fields, reverting them to the original values for a specific payment method, channel, and locale. + + + +```graphql +mutation { + translation { + deleteTranslations( + input: { + resourceType: PAYMENT_METHODS + channelId: "bc/store/channel/1" + localeId: "bc/store/locale/en-AU" + resources: [ + { + resourceId: "bc/store/paymentMethod/authorizenet.credit_card.USD" + fields: ["display_name", "payment_instruction"] + } + ] + } + ) { + errors { + __typename + ... on ValidationError { + message + } + ... on EntityNotFoundError { + id + message + } + ... on InvalidTranslationEntityFieldsError { + id + message + fields + } + } + } + } +} +``` + + +```json +{ + "data": { + "translation": { + "deleteTranslations": { + "errors": [] + } + } + } +} +``` + +