Traduzir o catálogo

Dispara a tradução automática do catálogo para um idioma, acompanha o job e cancela se for preciso.

Depois de habilitar um idioma, o conteúdo do catálogo (nomes e descrições de produtos, categorias, marcas, páginas, blog, banners, promoções, características, vendedores e outros) existe nele como cópia do idioma padrão. A tradução automática troca essas cópias por traduções geradas pelo provedor de IA configurado na loja. O trabalho é assíncrono: a chamada só enfileira um job e responde na hora; você acompanha o andamento consultando o job. Exige o privilégio manage_settings.

Disparar a tradução

POST/api/v1/admin/languages/{code}/translateAdmin

Enfileira a tradução automática do catálogo

Por padrão traduz as linhas cloned, stale e failed de todas as tabelas de conteúdo. Linhas já editadas por pessoas (human) ou aprovadas (approved) são preservadas, a menos que você peça o contrário. Se o idioma de destino for o padrão da loja, o job termina sem fazer nada. Cada item que falha é tentado 3 vezes e, se continuar falhando, fica failed sem interromper o resto do job.

Parâmetros de caminho

codestringobrigatório

Idioma de destino (es).

Corpo da requisição

tablesarray

Lista de tabelas de conteúdo a traduzir (product_descriptions, category_descriptions, brand_descriptions, page_descriptions, blog_post_descriptions, blog_category_descriptions, banner_descriptions, promotion_descriptions, product_option_descriptions, product_option_value_descriptions, attribute_value_descriptions, feature_descriptions, feature_group_descriptions, badge_descriptions, testimonial_descriptions, newsletter_descriptions, vendor_descriptions, layout_page_descriptions). Vazio ou ausente traduz todas. Nomes desconhecidos são ignorados em silêncio.

include_approvedbooleanpadrão: false

true também retraduz as linhas human e approved, sobrescrevendo o trabalho revisado.

O corpo é opcional: sem corpo, traduz tudo.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/languages/es/translate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tables":["product_descriptions","category_descriptions"]}'

202Job enfileirado

json

{ "job_id": "7c1a0f1e-52a8-4c58-9f0e-2d0c8a4f6b21" }

Acompanhar o job

GET/api/v1/admin/languages/{code}/translate/jobs/{id}Admin

Consulta o andamento de um job de tradução

Consulte a cada poucos segundos até status ser completed, failed ou canceled. O {code} na URL não é usado na busca: o job é achado pelo id.

Parâmetros de caminho

codestringobrigatório

Código do idioma do job.

iduuidobrigatório

Id devolvido em job_id.

200Job encontrado

json

{
  "id": "7c1a0f1e-52a8-4c58-9f0e-2d0c8a4f6b21",
  "lang_code": "es",
  "tables": ["product_descriptions", "category_descriptions"],
  "include_approved": false,
  "status": "running",
  "total_items": 183,
  "done_items": 54,
  "failed_items": 1,
  "created_at": "2026-10-11T14:20:00.000Z"
}

Campos da resposta

iduuid

Identificador do job.

lang_codestring

Idioma de destino.

tablesarray

Tabelas incluídas.

include_approvedboolean

Se linhas aprovadas e humanas entram.

statusstring

queuedrunningcompletedfailedcanceled

Estado do job.

total_itemsinteger

Total de itens. O valor definitivo só é gravado ao terminar; durante a execução pode estar em 0.

done_itemsinteger

Itens traduzidos com sucesso até agora.

failed_itemsinteger

Itens que falharam depois das tentativas.

errorstring

Mensagem de erro, quando o job falhou por inteiro. Ausente nos demais casos.

created_atstring

Criação (RFC 3339, UTC).

finished_atstring

Fim do job (RFC 3339, UTC). Ausente enquanto não terminou.

Cancelar o job

DELETE/api/v1/admin/languages/{code}/translate/jobs/{id}Admin

Cancela um job em fila ou em execução

Marca o job como canceled. O processamento para antes do próximo item; o que já foi traduzido permanece. Cancelar um job que já terminou, ou um id que não existe, não faz nada e também responde 204.

Parâmetros de caminho

codestringobrigatório

Código do idioma do job.

iduuidobrigatório

Id do job.

A resposta é 204 No Content.

Erros

Status	Quando	Corpo
400	Corpo JSON inválido (disparar)	`{"error":"invalid request body","detail":"..."}`
401	Sem token ou token expirado	`{"error":"missing authorization header"}`
403	Sem o privilégio `manage_settings`	`{"error":"insufficient privileges","required":"manage_settings"}`
404	Job inexistente (consultar)	`{"error":"job not found"}`
409	Já existe um job em fila ou em execução para o idioma	`{"error":"a translation job is already active for this language","detail":"..."}`
422	A loja não tem provedor de IA configurado; nada é enfileirado	`{"error":"provider_not_configured"}`
500	`id` que não é UUID, ou falha ao enfileirar	`{"error":"failed to read job","detail":"o valor \"abc\" não é um uuid válido. ..."}`

Veja também

Traduzir o catálogo

Dispara a tradução automática do catálogo para um idioma, acompanha o job e cancela se for preciso.

Disparar a tradução

POST/api/v1/admin/languages/{code}/translateAdmin

Enfileira a tradução automática do catálogo

Parâmetros de caminho

codestringobrigatório

Idioma de destino (es).

Corpo da requisição

tablesarray

include_approvedbooleanpadrão: false

true também retraduz as linhas human e approved, sobrescrevendo o trabalho revisado.

O corpo é opcional: sem corpo, traduz tudo.

Exemplo de requisição

bash

curl -X POST "$BASE_URL/api/v1/admin/languages/es/translate" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"tables":["product_descriptions","category_descriptions"]}'

202Job enfileirado

json

{ "job_id": "7c1a0f1e-52a8-4c58-9f0e-2d0c8a4f6b21" }

Acompanhar o job

GET/api/v1/admin/languages/{code}/translate/jobs/{id}Admin

Consulta o andamento de um job de tradução

Consulte a cada poucos segundos até status ser completed, failed ou canceled. O {code} na URL não é usado na busca: o job é achado pelo id.

Parâmetros de caminho

codestringobrigatório

Código do idioma do job.

iduuidobrigatório

Id devolvido em job_id.

200Job encontrado

json

{
  "id": "7c1a0f1e-52a8-4c58-9f0e-2d0c8a4f6b21",
  "lang_code": "es",
  "tables": ["product_descriptions", "category_descriptions"],
  "include_approved": false,
  "status": "running",
  "total_items": 183,
  "done_items": 54,
  "failed_items": 1,
  "created_at": "2026-10-11T14:20:00.000Z"
}

Campos da resposta

iduuid

Identificador do job.

lang_codestring

Idioma de destino.

tablesarray

Tabelas incluídas.

include_approvedboolean

Se linhas aprovadas e humanas entram.

statusstring

queuedrunningcompletedfailedcanceled

Estado do job.

total_itemsinteger

Total de itens. O valor definitivo só é gravado ao terminar; durante a execução pode estar em 0.

done_itemsinteger

Itens traduzidos com sucesso até agora.

failed_itemsinteger

Itens que falharam depois das tentativas.

errorstring

Mensagem de erro, quando o job falhou por inteiro. Ausente nos demais casos.

created_atstring

Criação (RFC 3339, UTC).

finished_atstring

Fim do job (RFC 3339, UTC). Ausente enquanto não terminou.

Cancelar o job

DELETE/api/v1/admin/languages/{code}/translate/jobs/{id}Admin

Cancela um job em fila ou em execução

Parâmetros de caminho

codestringobrigatório

Código do idioma do job.

iduuidobrigatório

Id do job.

A resposta é 204 No Content.

Erros

Status	Quando	Corpo
400	Corpo JSON inválido (disparar)	`{"error":"invalid request body","detail":"..."}`
401	Sem token ou token expirado	`{"error":"missing authorization header"}`
403	Sem o privilégio `manage_settings`	`{"error":"insufficient privileges","required":"manage_settings"}`
404	Job inexistente (consultar)	`{"error":"job not found"}`
409	Já existe um job em fila ou em execução para o idioma	`{"error":"a translation job is already active for this language","detail":"..."}`
422	A loja não tem provedor de IA configurado; nada é enfileirado	`{"error":"provider_not_configured"}`
500	`id` que não é UUID, ou falha ao enfileirar	`{"error":"failed to read job","detail":"o valor \"abc\" não é um uuid válido. ..."}`