DEVDOCS-6303-translations: [new] translations overview

docs/store-operations/translations/categories.mdx

@@ -0,0 +1,224 @@
+# Translations for Categories (Beta)
+
+<Callout type="info">
+The Translations Admin GraphQL API is currently available on Catalyst storefronts only.
+</Callout>
+
+
+The categories translatable fields are:
+
+* Name
+* Description
+* Page Title
+* Meta Keywords
+* Meta Description
+* Search Keywords
+
+## Examples
+
+Below are examples of GraphQL queries and mutations for retrieving and managing translation settings for categories.
+
+### Query translations
+
+This query returns a paginated list of translations by resourceType, channel and locale with a maximum of 50 results per request.  
+
+<Tabs items={['Request', 'Response']}>
+  <Tab>
+    ```json filename="Example mutation: Query a translation" showLineNumbers copy
+        GRAPHQL {{host}}/stores/{{store_hash}}/graphql
+        X-Auth-Token: {{token}}
+
+      query {
+          store {
+              translations(filters: {
+                  resourceType: CATEGORIES,
+                  channelId: "bc/store/channel/3",
+                  localeId: "bc/store/locale/en"
+              } first: 50) {
+                  edges {
+                      node {
+                            resourceId
+                              fields {
+                                  fieldName
+                                  original
+                                  translation
+                              }
+                          }
+                      cursor
+                  }
+              }
+          }
+      }
+    ```
+  </Tab>
+<Tab>
+```json filename="Example query: Query a translation" showLineNumbers copy
+   {
+  "data": {
+    "store": {
+      "translations": {
+        "edges": [
+          {
+            "node": {
+              "resourceId": "bc/store/category/24",
+              "fields": [
+                {
+                  "fieldName": "name",
+                  "original": "my channel level categories",
+                  "translation": "name (OVR) 1"
+                },
+                {
+                  "fieldName": "description",
+                  "original": "<p>my channel level categories description</p>",
+                  "translation": "description (OVR)"
+                },
+                {
+                  "fieldName": "page_title",
+                  "original": "Second Home page title",
+                  "translation": "page_title (OVR)"
+                },
+                {
+                  "fieldName": "meta_description",
+                  "original": "Second Meta description",
+                  "translation": "meta_description (OVR)"
+                },
+                {
+                  "fieldName": "search_keywords",
+                  "original": "Second Search keywords",
+                  "translation": "search_keywords (OVR)"
+                }
+              ]
+            },
+            "cursor": "eyJpZCI6MjR9"
+          }
+        ]
+      }
+    }
+  }
+}
+```
+</Tab>
+</Tabs>
+
+### Update a translation
+
+This mutation updates a translation.
+
+<Tabs items={['Request', 'Response']}>
+  <Tab>
+    ```json filename="Example mutation: Update a translation" showLineNumbers copy
+        GRAPHQL {{host}}/stores/{{store_hash}}/graphql
+        X-Auth-Token: {{token}}
+
+      mutation {
+        translation {
+            updateTranslations(input: {
+                resourceType: CATEGORIES,
+                channelId: "bc/store/channel/1",
+                localeId: "bc/store/locale/en",
+                entities: [
+                    {
+                        resourceId: "bc/store/category/18",
+                        fields: [
+                            {
+                              fieldName: "name",
+                              value: "name (OVR)"
+                            },
+                            {
+                              fieldName: "description",
+                              value: "description (OVR)"
+                            },
+                            {
+                              fieldName: "page_title",
+                              value: "page_title (OVR)"
+                            },
+                            {
+                              fieldName: "meta_description",
+                              value: "meta_description (OVR)"
+                            },
+                            {
+                              fieldName: "search_keywords",
+                              value: "search_keywords (OVR)"
+                        }
+                    ]
+                }
+            ]
+        }) {
+            __typename
+            errors {
+                __typename
+                ... on Error {
+                    message
+                }
+            }
+        }
+    }
+}
+```
+  </Tab>
+<Tab>
+```json filename="Example mutation: Update a translation" showLineNumbers copy
+ {
+    "data": {
+      "translation": {
+        "updateTranslations": {
+          "__typename": "UpdateTranslationsResult",
+          "errors": []
+        }
+      }
+    }
+  }
+```
+</Tab>
+</Tabs>
+
+### Delete a translation
+
+The following mutation deletes a translation.
+
+<Tabs items={['Request', 'Response']}>
+  <Tab>
+    ```json filename="Example mutation: Delete a translation" showLineNumbers copy
+        GRAPHQL {{host}}/stores/{{store_hash}}/graphql
+        X-Auth-Token: {{token}}
+
+      mutation {
+        translation {
+          deleteTranslations(input: {
+            resourceType: CATEGORIES,
+            channelId: "bc/store/channel/1",
+            localeId: "bc/store/locale/en",
+            resources: [
+                {
+                    resourceId: "bc/store/category/18",
+                    fields: ["name", "page_title", "meta_description"]
+                }
+            ]
+        }) {
+            __typename
+            errors {
+                __typename
+                ... on Error {
+                    message
+                }
+            }
+        }
+    }
+}
+```
+  </Tab>
+<Tab>
+```json filename="Example mutation: Delete a translation" showLineNumbers copy
+ {
+  "data": {
+    "translation": {
+      "deleteTranslations": {
+        "__typename": "DeleteTranslationsResult",
+        "errors": []
+      }
+    }
+  }
+}
+```
+</Tab>
+</Tabs>

docs/store-operations/translations/index.mdx

@@ -0,0 +1,41 @@
+# Translations Admin GraphQL API (Beta)
+
+## Overview
+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 components, and more are expected in the future:
+
+* Categories
+* Locations
+
+## Purpose and Benefits
+The API helps merchants localize their storefronts efficiently, enabling a consistent shopping experience across multiple languages. This allows merchants to cater to a broader audience and expand market reach.
+
+## Authentication and Access
+Access to the Translations Admin GraphQL API requires valid API credentials. GraphQL Admin API endpoints use the X-Auth-Token header to authenticate to BigCommerce servers. To make a call to the Admin GraphQL, use an API client tool such as [Postman](https://www.postman.com/). Ensure authentication tokens are included in requests.
+
+## OAuth scopes
+
+| 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).
+
+
+## Limitations
+
+* Currently in Beta and subject to changes
+* Rate limits apply
+* Only available on Catalyst storefronts
+
+## Best Practices
+* Cache translations to minimize API calls.
+* Avoid redundant translations by checking existing translations first
+
+## Resources
+* [Translation for Categories (Beta)](/docs/store-operations/translations/categories.mdx)
+* [Translation for Locations (Beta)](/docs/store-operations/translations/locations.mdx)