Skip to content

Commit b41df0b

Browse files
bc-terrabc-terra
authored
DEVDOCS-6490 - Add documentation for product custom field translations (#1095)
This document provides comprehensive information on managing product custom field translations using the GraphQL API, including querying, updating, and deleting translations. <!-- Ticket number or summary of work --> # [DEVDOCS-6490] ## What changed? <!-- Provide a bulleted list in the present tense --> * ## Release notes draft <!-- Provide an entry for the release notes using simple, conversational language. Don't be too technical. Explain how the change will benefit the merchant and link to the feature. Examples: * The newly-released [X feature] is now available to use. Now, you’ll be able to [perform Y action]. * We're happy to announce [X feature], which can help you [perform Y action]. * [X feature] helps you to create [Y response] using the [Z query parameter]. Now, you can deliver [ex, localized shopping experiences for your customers]. * Fixed a bug in the [X endpoint]. Now the [Y field] will appear when you click [Z option]. --> * ## Anything else? <!-- Add related PRs, salient notes, additional ticket numbers, etc. --> ping {names} [DEVDOCS-6490]: https://bigcommercecloud.atlassian.net/browse/DEVDOCS-6490?atlOrigin=eyJpIjoiNWRkNTljNzYxNjVmNDY3MDlhMDU5Y2ZhYzA5YTRkZjUiLCJwIjoiZ2l0aHViLWNvbS1KU1cifQ
1 parent 7eefcb1 commit b41df0b

File tree

2 files changed

+315
-0
lines changed

2 files changed

+315
-0
lines changed

‎docs/store-operations/translations/index.mdx‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,8 @@ The API currently supports translations for the following resource types, and mo
1010
* Categories
1111
* Brands
1212
* Locations
13+
* Products
14+
* Custom Fields
1315

1416
<Callout type="info">
1517
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.

‎docs/store-operations/translations/product-custom-fields.mdx‎

Lines changed: 313 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,313 @@
1+
# Translations for Product Custom Fields (Beta)
2+
3+
<Callout type='info'>
4+
The Translations Admin GraphQL API for managing product custom field translations is available on Catalyst storefronts only.
5+
</Callout>
6+
7+
The product custom fields translatable data points are:
8+
9+
- Name
10+
- Value
11+
12+
## Querying Product Custom Field Translations (Storefront API)
13+
14+
Product custom field translations are returned in the current locale determined by the context (e.g., `Accept-Language` header, channel settings, or session locale).
15+
16+
### Example: Query a product custom field in a given locale
17+
18+
<Tabs items={['Request', 'Response']}>
19+
<Tab>
20+
21+
```graphql filename="Example query: Query product custom field in a locale" showLineNumbers copy
22+
GRAPHQL https://storefront.example.com/graphql
23+
Accept-Language: es
24+
25+
query {
26+
site {
27+
product(entityId: "123") {
28+
entityId
29+
customFields {
30+
entityId
31+
name
32+
value
33+
}
34+
}
35+
}
36+
}
37+
```
38+
39+
</Tab>
40+
<Tab>
41+
42+
```json filename="Example query: Query product custom field in a locale" showLineNumbers copy
43+
{
44+
"data": {
45+
"site": {
46+
"product": {
47+
"entityId": "123",
48+
"customFields": [
49+
{
50+
"entityId": "456",
51+
"name": "Material",
52+
"value": "Algodón"
53+
}
54+
]
55+
}
56+
}
57+
}
58+
}
59+
```
60+
</Tab>
61+
</Tabs>
62+
63+
## Managing Product Custom Field Translations (Admin API)
64+
65+
Product custom field translation management (list, update, delete) is available via the Admin GraphQL API. These mutations and queries are not available on the Storefront API.
66+
67+
### Query a List of Product Custom Field Translations
68+
69+
<Tabs items={['Request', 'Response']}>
70+
<Tab>
71+
72+
```graphql filename="Example query: Query a list of product custom field translations" showLineNumbers copy
73+
GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql
74+
X-Auth-Token: {{token}}
75+
76+
query {
77+
store {
78+
translations(filters: {
79+
resourceType: PRODUCT_CUSTOM_FIELDS,
80+
channelId: "bc/store/channel/5",
81+
localeId: "bc/store/locale/es"
82+
} first: 50) {
83+
edges {
84+
node {
85+
resourceId
86+
fields {
87+
fieldName
88+
original
89+
translation
90+
}
91+
}
92+
cursor
93+
}
94+
}
95+
}
96+
}
97+
```
98+
99+
</Tab>
100+
<Tab>
101+
102+
```json filename="Example query: Query a list of product custom field translations" showLineNumbers copy
103+
{
104+
"data": {
105+
"store": {
106+
"translations": {
107+
"edges": [
108+
{
109+
"node": {
110+
"resourceId": "bc/store/product-custom-field/456",
111+
"fields": [
112+
{
113+
"fieldName": "name",
114+
"original": "Material",
115+
"translation": "Material (ES)"
116+
},
117+
{
118+
"fieldName": "value",
119+
"original": "Cotton",
120+
"translation": "Algodón"
121+
}
122+
]
123+
},
124+
"cursor": "eyJpZCI6NDU2fQ"
125+
}
126+
]
127+
}
128+
}
129+
}
130+
}
131+
```
132+
</Tab>
133+
</Tabs>
134+
135+
### Query a Product Custom Field Translation by Resource ID
136+
137+
<Callout type='warning'>
138+
When querying a translation by resourceId, you must provide the full resourceId in the format `bc/store/product-custom-field/{custom_field_id}`.
139+
</Callout>
140+
141+
<Tabs items={['Request', 'Response']}>
142+
<Tab>
143+
144+
```graphql filename="Example query: Query a product custom field translation by id" showLineNumbers copy
145+
GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql
146+
X-Auth-Token: {{token}}
147+
148+
query {
149+
store {
150+
translations(filters: {
151+
resourceType: PRODUCT_CUSTOM_FIELDS,
152+
channelId: "bc/store/channel/4",
153+
localeId: "bc/store/locale/fr",
154+
resourceIds: ["bc/store/product-custom-field/456"]
155+
}) {
156+
edges {
157+
node {
158+
resourceId
159+
fields {
160+
fieldName
161+
original
162+
translation
163+
}
164+
}
165+
cursor
166+
}
167+
}
168+
}
169+
}
170+
```
171+
172+
</Tab>
173+
<Tab>
174+
175+
```json filename="Example query: Query a product custom field translation by id" showLineNumbers copy
176+
{
177+
"data": {
178+
"store": {
179+
"translations": {
180+
"edges": [
181+
{
182+
"node": {
183+
"resourceId": "bc/store/product-custom-field/456",
184+
"fields": [
185+
{
186+
"fieldName": "name",
187+
"original": "Material",
188+
"translation": "Matériel (FR)"
189+
},
190+
{
191+
"fieldName": "value",
192+
"original": "Cotton",
193+
"translation": "Coton"
194+
}
195+
]
196+
},
197+
"cursor": "eyJpZCI6NDU2fQ"
198+
}
199+
]
200+
}
201+
}
202+
}
203+
}
204+
```
205+
</Tab>
206+
</Tabs>
207+
208+
### Update a Product Custom Field Translation
209+
210+
<Tabs items={['Request', 'Response']}>
211+
<Tab>
212+
213+
```graphql filename="Example mutation: Update a product custom field translation" showLineNumbers copy
214+
GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql
215+
X-Auth-Token: {{token}}
216+
217+
mutation {
218+
translation {
219+
updateTranslations(input: {
220+
resourceType: PRODUCT_CUSTOM_FIELDS,
221+
channelId: "bc/store/channel/2",
222+
localeId: "bc/store/locale/es",
223+
entities: [
224+
{
225+
resourceId: "bc/store/product-custom-field/456",
226+
fields: [
227+
{ fieldName: "name", value: "Material (ES)" },
228+
{ fieldName: "value", value: "Algodón" }
229+
]
230+
}
231+
]
232+
}) {
233+
__typename
234+
errors {
235+
__typename
236+
... on Error {
237+
message
238+
}
239+
}
240+
}
241+
}
242+
}
243+
```
244+
245+
</Tab>
246+
<Tab>
247+
248+
```json filename="Example mutation: Update a product custom field translation" showLineNumbers copy
249+
{
250+
"data": {
251+
"translation": {
252+
"updateTranslations": {
253+
"__typename": "UpdateTranslationsResult",
254+
"errors": []
255+
}
256+
}
257+
}
258+
}
259+
```
260+
</Tab>
261+
</Tabs>
262+
263+
### Delete a Product Custom Field Translation
264+
265+
<Tabs items={['Request', 'Response']}>
266+
<Tab>
267+
268+
```graphql filename="Example mutation: Delete a product custom field translation" showLineNumbers copy
269+
GRAPHQL https://api.bigcommerce.com/stores/{{store_hash}}/graphql
270+
X-Auth-Token: {{token}}
271+
272+
mutation {
273+
translation {
274+
deleteTranslations(input: {
275+
resourceType: PRODUCT_CUSTOM_FIELDS,
276+
channelId: "bc/store/channel/2",
277+
localeId: "bc/store/locale/es",
278+
resources: [
279+
{
280+
resourceId: "bc/store/product-custom-field/456",
281+
fields: ["name", "value"]
282+
}
283+
]
284+
}) {
285+
__typename
286+
errors {
287+
__typename
288+
... on Error {
289+
message
290+
}
291+
}
292+
}
293+
}
294+
}
295+
```
296+
297+
</Tab>
298+
<Tab>
299+
300+
```json filename="Example mutation: Delete a product custom field translation" showLineNumbers copy
301+
{
302+
"data": {
303+
"translation": {
304+
"deleteTranslations": {
305+
"__typename": "DeleteTranslationsResult",
306+
"errors": []
307+
}
308+
}
309+
}
310+
}
311+
```
312+
</Tab>
313+
</Tabs>

0 commit comments

Comments
 (0)