diff --git a/docs/store-operations/translations/index.mdx b/docs/store-operations/translations/index.mdx index 556f96964..abf022488 100644 --- a/docs/store-operations/translations/index.mdx +++ b/docs/store-operations/translations/index.mdx @@ -22,8 +22,10 @@ The API currently supports translations for the following resource types, and mo 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? @@ -43,10 +45,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). 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": [] + } + } + } +} +``` + +