diff --git a/docs/store-operations/translations/address-form-fields.mdx b/docs/store-operations/translations/address-form-fields.mdx new file mode 100644 index 000000000..89e48a07a --- /dev/null +++ b/docs/store-operations/translations/address-form-fields.mdx @@ -0,0 +1,357 @@ +# Translations for Address Form Fields (Beta) + + + The Translations Admin GraphQL API is currently available on Catalyst + storefronts only. + + +The following entities are translatable for address form fields: + +- Label as `label` - The display label for the form field +- Option values as `option_{base64string}` - Option values where the base64 string encodes the original option text + +## Resource fields + +The entities listed above are referenced differently based on resource type and must use the following values in the queries outlined below: +| Entity Type | `resourceType` | `resourceId` Format | +| --- | --- | --- | +| Address Form Field | `ADDRESS_FORM_FIELDS` | `bc/store/addressFormField/{field_id}` | + +### Field Name Format for Options + +- `label` - The display label for the form field +- `option_{base64string}` - Option values where the base64 string encodes the original option text + - Example: `option_UmVzaWRlbnRpYWw=` (where `UmVzaWRlbnRpYWw=` is base64 for "Residential") + - Example: `option_Q29tbWVyY2lhbA==` (where `Q29tbWVyY2lhbA==` is base64 for "Commercial") + +## Examples + +Below are examples of GraphQL queries and mutations for retrieving and managing translation settings for address form fields. + +### Query a List of Translations + +This query returns a paginated list of translations by resourceType, channel, and locale with a maximum of 50 results per request. + +The request below uses several variables for reusability. Replace `{{channel_id}}` and `{{locale_code}}` with the appropriate values for your use case. + + + + +```graphql filename="Example query: Query a list of translations" showLineNumbers copy +GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql +X-Auth-Token: {{token}} + +query { + store { + translations( + filters: { + channelId: "bc/store/channel/{{channel_id}}", + localeId: "bc/store/locale/{{locale_code}}", + resourceType: ADDRESS_FORM_FIELDS + } + first: 50 + ) { + pageInfo { + startCursor + endCursor + hasNextPage + hasPreviousPage + } + edges { + cursor + node { + resourceId + fields { + fieldName + original + translation + } + } + } + } + } +} +``` + + + + +```json filename="Example query: Query a list of translations" showLineNumbers copy +{ + "data": { + "store": { + "translations": { + "pageInfo": { + "startCursor": "YXJyYXljb25uZWN0aW9uOjA=", + "endCursor": "YXJyYXljb25uZWN0aW9uOjA=", + "hasNextPage": false, + "hasPreviousPage": false + }, + "edges": [ + { + "cursor": "YXJyYXljb25uZWN0aW9uOjA=", + "node": { + "resourceId": "bc/store/addressFormField/18", + "fields": [ + { + "fieldName": "label", + "original": "Street Address", + "translation": "Dirección" + }, + { + "fieldName": "option_UmVzaWRlbnRpYWw=", + "original": "Residential", + "translation": "Residencial" + }, + { + "fieldName": "option_Q29tbWVyY2lhbA==", + "original": "Commercial", + "translation": "Comercial" + } + ] + } + } + ] + } + } + } +} +``` + + + + +### Query a Translation by Resource ID + +This query returns translation(s) by resourceId. + +The request below uses several variables for reusability. Replace `{{resourceId}}`, `{{channel_id}}`, and `{{locale_code}}` with appropriate values for your use case. Make sure `resourceId` follows the format from the [Resource fields](#resource-fields) table. + + + + +```graphql filename="Example query: Query a translation by resource id" showLineNumbers copy +GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql +X-Auth-Token: {{token}} + +query { + store { + translations( + filters: { + channelId: "bc/store/channel/{{channel_id}}", + localeId: "bc/store/locale/{{locale_code}}", + resourceType: ADDRESS_FORM_FIELDS, + resourceIds: ["bc/store/addressFormField/18"] + } + ) { + edges { + cursor + node { + resourceId + fields { + fieldName + original + translation + } + } + } + } + } +} +``` + + + + +```json filename="Example query: Query a translation by resource id" showLineNumbers copy +{ + "data": { + "store": { + "translations": { + "edges": [ + { + "cursor": "YXJyYXljb25uZWN0aW9uOjA=", + "node": { + "resourceId": "bc/store/addressFormField/18", + "fields": [ + { + "fieldName": "label", + "original": "Street Address", + "translation": "Dirección" + }, + { + "fieldName": "option_UmVzaWRlbnRpYWw=", + "original": "Residential", + "translation": "Residencial" + }, + { + "fieldName": "option_Q29tbWVyY2lhbA==", + "original": "Commercial", + "translation": "Comercial" + } + ] + } + } + ] + } + } + } +} +``` + + + + +### Update a Translation + +This mutation updates a translation. + + + + +```graphql filename="Example mutation: Update a translation" showLineNumbers copy +GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql +X-Auth-Token: {{token}} + +mutation { + translation { + updateTranslations( + input: { + resourceType: ADDRESS_FORM_FIELDS, + channelId: "bc/store/channel/{{channel_id}}", + localeId: "bc/store/locale/{{locale_code}}", + entities: [ + { + resourceId: "bc/store/addressFormField/18", + fields: [ + { fieldName: "label", value: "Dirección de la calle" }, + { fieldName: "option_UmVzaWRlbnRpYWw=", value: "Residencial" }, + { fieldName: "option_Q29tbWVyY2lhbA==", value: "Comercial" } + ] + } + ] + } + ) { + __typename + errors { + __typename + ... on Error { + message + } + ... on InvalidTranslationEntityFieldsError { + id + fields + message + } + } + } + } +} +``` + + + + +```json filename="Example mutation: Update a translation" showLineNumbers copy +{ + "data": { + "translation": { + "updateTranslations": { + "__typename": "UpdateTranslationsResult", + "errors": [] + } + } + } +} +``` + + + + + +The mutation example above shows a successful response. If invalid fields are provided, the API will return an error response. See the [Error Handling Reference](/docs/store-operations/translations/errors) for more details on error responses. + +Example error response for invalid fields: +```json +{ + "data": { + "translation": { + "updateTranslations": { + "__typename": "UpdateTranslationsResult", + "errors": [ + { + "__typename": "InvalidTranslationEntityFieldsError", + "id": "bc/store/addressFormField/18", + "fields": ["option_SW52YWxpZA=="], + "message": "Invalid fields for entity bc/store/addressFormField/18: option_SW52YWxpZA==" + } + ] + } + } + } +} +``` + + +### Delete a Translation + +The following mutation deletes a translation. + + + + +```graphql filename="Example mutation: Delete a translation" showLineNumbers copy +GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql +X-Auth-Token: {{token}} + +mutation { + translation { + deleteTranslations( + input: { + channelId: "bc/store/channel/{{channel_id}}", + localeId: "bc/store/locale/{{locale_code}}", + resourceType: ADDRESS_FORM_FIELDS, + resources: [ + { + resourceId: "bc/store/addressFormField/18", + fields: ["label", "option_UmVzaWRlbnRpYWw=", "option_Q29tbWVyY2lhbA=="] + } + ] + } + ) { + __typename + errors { + __typename + ... on Error { + message + } + ... on InvalidTranslationEntityFieldsError { + id + fields + message + } + } + } + } +} +``` + + + + +```json filename="Example mutation: Delete a translation" showLineNumbers copy +{ + "data": { + "translation": { + "deleteTranslations": { + "__typename": "DeleteTranslationsResult", + "errors": [] + } + } + } +} +``` + + + + diff --git a/docs/store-operations/translations/checkout-settings.mdx b/docs/store-operations/translations/checkout-settings.mdx new file mode 100644 index 000000000..5e02a171c --- /dev/null +++ b/docs/store-operations/translations/checkout-settings.mdx @@ -0,0 +1,290 @@ +# Translations for Checkout Settings (Beta) + + + The Translations Admin GraphQL API is currently available on Catalyst + storefronts only. + + +The following entities are translatable for checkout settings: + +- Content as `content` - The text content of checkout settings (e.g., terms and conditions) + +## Resource fields + +The entities listed above are referenced differently based on resource type and must use the following values in the queries outlined below: +| Entity Type | `resourceType` | `resourceId` Format | +| --- | --- | --- | +| Checkout Setting | `CHECKOUT_SETTINGS` | `bc/store/checkoutSettings/{settingName}` | + +### Known Checkout Settings Resources + +- `OrderTermsAndConditionsTextarea` - The terms and conditions textarea on checkout + +## Examples + +Below are examples of GraphQL queries and mutations for retrieving and managing translation settings for checkout settings. + +### Query a List of Translations + +This query returns a paginated list of translations by resourceType, channel, and locale with a maximum of 50 results per request. + +The request below uses several variables for reusability. Replace `{{channel_id}}` and `{{locale_code}}` with the appropriate values for your use case. + + + + +```graphql filename="Example query: Query a list of translations" showLineNumbers copy +GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql +X-Auth-Token: {{token}} + +query { + store { + translations(filters: { + resourceType: CHECKOUT_SETTINGS, + channelId: "bc/store/channel/{{channel_id}}", + localeId: "bc/store/locale/{{locale_code}}" + } first: 50) { + edges { + node { + resourceId + fields { + fieldName + original + translation + } + } + cursor + } + pageInfo { + hasNextPage + hasPreviousPage + startCursor + endCursor + } + } + } +} +``` + + + + +```json filename="Example query: Query a list of translations" showLineNumbers copy +{ + "data": { + "store": { + "translations": { + "edges": [ + { + "node": { + "resourceId": "bc/store/checkoutSettings/OrderTermsAndConditionsTextarea", + "fields": [ + { + "fieldName": "content", + "original": "Original terms and conditions text", + "translation": "Translated terms and conditions text" + } + ] + }, + "cursor": "checkout_cursor_1" + } + ], + "pageInfo": { + "hasNextPage": false, + "hasPreviousPage": false, + "startCursor": "checkout_cursor_1", + "endCursor": "checkout_cursor_1" + } + } + } + } +} +``` + + + + +### Query a Translation by Resource ID + +This query returns a translation by resourceId. + +The request below uses several variables for reusability. Replace `{{resourceId}}`, `{{channel_id}}`, and `{{locale_code}}` with appropriate values for your use case. Make sure `resourceId` follows the format from the [Resource fields](#resource-fields) table. + + + + +```graphql filename="Example query: Query a translation by id" showLineNumbers copy +GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql +X-Auth-Token: {{token}} + +query { + store { + translations(filters: { + resourceType: CHECKOUT_SETTINGS, + channelId: "bc/store/channel/{{channel_id}}", + localeId: "bc/store/locale/{{locale_code}}", + resourceIds: ["{{resourceId}}"] + }) { + edges { + node { + resourceId + fields { + fieldName + original + translation + } + } + cursor + } + } + } +} +``` + + + + +```json filename="Example query: Query a translation by id" showLineNumbers copy +{ + "data": { + "store": { + "translations": { + "edges": [ + { + "node": { + "resourceId": "bc/store/checkoutSettings/OrderTermsAndConditionsTextarea", + "fields": [ + { + "fieldName": "content", + "original": "Original terms and conditions text", + "translation": "Translated terms and conditions text" + } + ] + }, + "cursor": "checkout_cursor_1" + } + ] + } + } + } +} +``` + + + + +### Update a Translation + + + + +The request below is for updating a checkout setting translation. + +```graphql filename="Example mutation: Update a translation" showLineNumbers copy +GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql +X-Auth-Token: {{token}} + +mutation { + translation { + updateTranslations(input: { + resourceType: CHECKOUT_SETTINGS, + channelId: "bc/store/channel/{{channel_id}}", + localeId: "bc/store/locale/{{locale_code}}", + entities: [ + { + resourceId: "bc/store/checkoutSettings/OrderTermsAndConditionsTextarea", + fields: [ + { + fieldName: "content", + value: "Updated terms and conditions in French" + } + ] + } + ] + }) { + __typename + errors { + __typename + ... on Error { + message + } + } + } + } +} +``` + + + + +```json filename="Example mutation: Update a translation" showLineNumbers copy +{ + "data": { + "translation": { + "updateTranslations": { + "__typename": "UpdateTranslationsResult", + "errors": [] + } + } + } +} +``` + + + + +### Delete a Translation + +The request below is for deleting translations on a checkout setting. + + + + +```graphql filename="Example mutation: Delete a translation" showLineNumbers copy +GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql +X-Auth-Token: {{token}} + +mutation { + translation { + deleteTranslations(input: { + resourceType: CHECKOUT_SETTINGS, + channelId: "bc/store/channel/{{channel_id}}", + localeId: "bc/store/locale/{{locale_code}}", + resources: [ + { + resourceId: "bc/store/checkoutSettings/OrderTermsAndConditionsTextarea", + fields: ["content"] + } + ] + }) { + __typename + errors { + __typename + ... on Error { + message + } + } + } + } +} +``` + + + + +```json filename="Example mutation: Delete a translation" showLineNumbers copy +{ + "data": { + "translation": { + "deleteTranslations": { + "__typename": "DeleteTranslationsResult", + "errors": [] + } + } + } +} +``` + + + + diff --git a/docs/store-operations/translations/customer-form-fields.mdx b/docs/store-operations/translations/customer-form-fields.mdx new file mode 100644 index 000000000..4c80e99e1 --- /dev/null +++ b/docs/store-operations/translations/customer-form-fields.mdx @@ -0,0 +1,413 @@ +# Translations for Customer Form Fields (Beta) + + + The Translations Admin GraphQL API is currently available on Catalyst + storefronts only. + + +The following entities are translatable for customer form fields: + +- Label as `label` - The display label for the form field +- Option values as `option_{base64string}` - Option values where the base64 string encodes the original option text + +## Resource fields + +The entities listed above are referenced differently based on resource type and must use the following values in the queries outlined below: +| Entity Type | `resourceType` | `resourceId` Format | +| --- | --- | --- | +| Customer Form Field | `CUSTOMER_FORM_FIELDS` | `bc/store/customerFormField/{field_id}` | + +### Field Name Format for Options + +- `label` - The display label for the form field +- `option_{base64string}` - Option values where the base64 string encodes the original option text + - Example: `option_SG9tZSBBZGRyZXNz` (where `SG9tZSBBZGRyZXNz` is base64 for "Home Address") + - Example: `option_TW9iaWxl` (where `TW9iaWxl` is base64 for "Mobile") + +## Examples + +Below are examples of GraphQL queries and mutations for retrieving and managing translation settings for customer form fields. + +### Query a List of Translations + +This query returns a paginated list of translations by resourceType, channel, and locale with a maximum of 50 results per request. + +The request below uses several variables for reusability. Replace `{{channel_id}}` and `{{locale_code}}` with the appropriate values for your use case. + + + + +```graphql filename="Example query: Query a list of translations" showLineNumbers copy +GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql +X-Auth-Token: {{token}} + +query { + store { + translations( + filters: { + channelId: "bc/store/channel/{{channel_id}}", + localeId: "bc/store/locale/{{locale_code}}", + resourceType: CUSTOMER_FORM_FIELDS + } + first: 50 + ) { + pageInfo { + startCursor + endCursor + hasNextPage + hasPreviousPage + } + edges { + cursor + node { + resourceId + fields { + fieldName + original + translation + } + } + } + } + } +} +``` + + + + +```json filename="Example query: Query a list of translations" showLineNumbers copy +{ + "data": { + "store": { + "translations": { + "pageInfo": { + "startCursor": "YXJyYXljb25uZWN0aW9uOjA=", + "endCursor": "YXJyYXljb25uZWN0aW9uOjE=", + "hasNextPage": false, + "hasPreviousPage": false + }, + "edges": [ + { + "cursor": "YXJyYXljb25uZWN0aW9uOjA=", + "node": { + "resourceId": "bc/store/customerFormField/18", + "fields": [ + { + "fieldName": "label", + "original": "Address Line 1", + "translation": "Ligne d'adresse 1" + }, + { + "fieldName": "option_SG9tZSBBZGRyZXNz", + "original": "Home Address", + "translation": "Adresse domicile" + }, + { + "fieldName": "option_V29yayBBZGRyZXNz", + "original": "Work Address", + "translation": "Adresse professionnelle" + } + ] + } + }, + { + "cursor": "YXJyYXljb25uZWN0aW9uOjE=", + "node": { + "resourceId": "bc/store/customerFormField/19", + "fields": [ + { + "fieldName": "label", + "original": "Phone Number", + "translation": "Numéro de téléphone" + }, + { + "fieldName": "option_TW9iaWxl", + "original": "Mobile", + "translation": "Portable" + }, + { + "fieldName": "option_SG9tZQ==", + "original": "Home", + "translation": "Domicile" + } + ] + } + } + ] + } + } + } +} +``` + + + + +### Query a Translation by Resource ID + +This query returns translation(s) by resourceId. + +The request below uses several variables for reusability. Replace `{{resourceId}}`, `{{channel_id}}`, and `{{locale_code}}` with appropriate values for your use case. Make sure `resourceId` follows the format from the [Resource fields](#resource-fields) table. + + + + +```graphql filename="Example query: Query a translation by resource id" showLineNumbers copy +GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql +X-Auth-Token: {{token}} + +query { + store { + translations( + filters: { + channelId: "bc/store/channel/{{channel_id}}", + localeId: "bc/store/locale/{{locale_code}}", + resourceType: CUSTOMER_FORM_FIELDS, + resourceIds: ["bc/store/customerFormField/18", "bc/store/customerFormField/19"] + } + ) { + edges { + cursor + node { + resourceId + fields { + fieldName + original + translation + } + } + } + } + } +} +``` + + + + +```json filename="Example query: Query a translation by resource id" showLineNumbers copy +{ + "data": { + "store": { + "translations": { + "edges": [ + { + "cursor": "YXJyYXljb25uZWN0aW9uOjA=", + "node": { + "resourceId": "bc/store/customerFormField/18", + "fields": [ + { + "fieldName": "label", + "original": "Address Line 1", + "translation": "Ligne d'adresse 1" + }, + { + "fieldName": "option_SG9tZSBBZGRyZXNz", + "original": "Home Address", + "translation": "Adresse domicile" + }, + { + "fieldName": "option_V29yayBBZGRyZXNz", + "original": "Work Address", + "translation": "Adresse professionnelle" + } + ] + } + }, + { + "cursor": "YXJyYXljb25uZWN0aW9uOjE=", + "node": { + "resourceId": "bc/store/customerFormField/19", + "fields": [ + { + "fieldName": "label", + "original": "Phone Number", + "translation": "Numéro de téléphone" + }, + { + "fieldName": "option_TW9iaWxl", + "original": "Mobile", + "translation": "Portable" + }, + { + "fieldName": "option_SG9tZQ==", + "original": "Home", + "translation": "Domicile" + } + ] + } + } + ] + } + } + } +} +``` + + + + +### Update a Translation + +This mutation updates a translation. + + + + +```graphql filename="Example mutation: Update a translation" showLineNumbers copy +GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql +X-Auth-Token: {{token}} + +mutation { + translation { + updateTranslations( + input: { + resourceType: CUSTOMER_FORM_FIELDS, + channelId: "bc/store/channel/{{channel_id}}", + localeId: "bc/store/locale/{{locale_code}}", + entities: [ + { + resourceId: "bc/store/customerFormField/18", + fields: [ + { fieldName: "label", value: "Adresse personnalisée" }, + { fieldName: "option_SG9tZSBBZGRyZXNz", value: "Adresse domicile" }, + { fieldName: "option_V29yayBBZGRyZXNz", value: "Adresse bureau" } + ] + }, + { + resourceId: "bc/store/customerFormField/19", + fields: [ + { fieldName: "label", value: "Téléphone" }, + { fieldName: "option_TW9iaWxl", value: "Portable" }, + { fieldName: "option_SG9tZQ==", value: "Fixe" } + ] + } + ] + } + ) { + __typename + errors { + __typename + ... on Error { + message + } + ... on InvalidTranslationEntityFieldsError { + id + fields + message + } + } + } + } +} +``` + + + + +```json filename="Example mutation: Update a translation" showLineNumbers copy +{ + "data": { + "translation": { + "updateTranslations": { + "__typename": "UpdateTranslationsResult", + "errors": [] + } + } + } +} +``` + + + + + +The mutation example above shows a successful response. If an entity is not found, the API will return an error response. See the [Error Handling Reference](/docs/store-operations/translations/errors) for more details on error responses. + +Example error response for entity not found: +```json +{ + "data": { + "translation": { + "updateTranslations": { + "__typename": "UpdateTranslationsResult", + "errors": [ + { + "__typename": "EntityNotFoundError", + "message": "Entity bc/store/customerFormField/999 not found." + } + ] + } + } + } +} +``` + + +### Delete a Translation + +The following mutation deletes a translation. + + + + +```graphql filename="Example mutation: Delete a translation" showLineNumbers copy +GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql +X-Auth-Token: {{token}} + +mutation { + translation { + deleteTranslations( + input: { + channelId: "bc/store/channel/{{channel_id}}", + localeId: "bc/store/locale/{{locale_code}}", + resourceType: CUSTOMER_FORM_FIELDS, + resources: [ + { + resourceId: "bc/store/customerFormField/18", + fields: ["label", "option_SG9tZSBBZGRyZXNz", "option_V29yayBBZGRyZXNz"] + }, + { + resourceId: "bc/store/customerFormField/19", + fields: ["label", "option_TW9iaWxl"] + } + ] + } + ) { + __typename + errors { + __typename + ... on Error { + message + } + ... on InvalidTranslationEntityFieldsError { + id + fields + message + } + } + } + } +} +``` + + + + +```json filename="Example mutation: Delete a translation" showLineNumbers copy +{ + "data": { + "translation": { + "deleteTranslations": { + "__typename": "DeleteTranslationsResult", + "errors": [] + } + } + } +} +``` + + + + diff --git a/docs/store-operations/translations/index.mdx b/docs/store-operations/translations/index.mdx index e71378314..556f96964 100644 --- a/docs/store-operations/translations/index.mdx +++ b/docs/store-operations/translations/index.mdx @@ -1,7 +1,6 @@ # 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. @@ -16,6 +15,10 @@ The API currently supports translations for the following resource types, and mo * Brands * [Product Filters](/docs/store-operations/translations/filters) * [Locations](/docs/store-operations/translations/locations) +* [Payment Methods](/docs/store-operations/translations/payments) +* [Address Form Fields](/docs/store-operations/translations/address-form-fields) +* [Customer Form Fields](/docs/store-operations/translations/customer-form-fields) +* [Checkout Settings](/docs/store-operations/translations/checkout-settings) Refer to the [Error Handling](/docs/store-operations/translations/errors) guide for understanding and handling errors while managing translations. @@ -74,4 +77,8 @@ For more information on OAuth Scopes, see our [Guide to API Accounts](/docs/star - [Product Listing Page Translations](/docs/store-operations/translations/listings) - [Product Filter Translations](/docs/store-operations/translations/filters) - [Inventory Locations Translations](/docs/store-operations/translations/locations) +- [Payment Methods Translations](/docs/store-operations/translations/payments) +- [Address Form Fields Translations](/docs/store-operations/translations/address-form-fields) +- [Customer Form Fields Translations](/docs/store-operations/translations/customer-form-fields) +- [Checkout Settings Translations](/docs/store-operations/translations/checkout-settings) - [Error Handling Reference](/docs/store-operations/translations/errors)