Cobertura e revisão

Mede quanto do catálogo já foi traduzido e revisa, aprova ou retraduz o que a máquina produziu.

Depois da tradução automática, o texto gerado ainda não é confiável até alguém revisar. Estas quatro rotas medem o andamento e permitem aprovar ou refazer itens. Todas exigem o privilégio manage_settings. A unidade de revisão é uma entidade de uma tabela (um produto, uma categoria...), com todos os seus campos de texto.

Cobertura por tabela

GET/api/v1/admin/languages/{code}/coverageAdmin

Cobertura da tradução por tabela de conteúdo

Conta, para cada tabela de conteúdo, quantas linhas existem no idioma e em que estado de tradução estão. Tabelas que não existem na loja são omitidas.

Parâmetros de caminho

codestringobrigatório

Código do idioma.

200Cobertura calculada

json

{
  "language": "es",
  "tables": [
    {
      "table": "product_descriptions",
      "total": 136,
      "machine": 100,
      "approved": 10,
      "human": 2,
      "stale": 4,
      "cloned": 20,
      "failed": 0,
      "coverage_pct": 82.4
    }
  ]
}

Campos da resposta

languagestring

Idioma consultado.

tables[].tablestring

Nome da tabela de conteúdo.

tables[].totalinteger

Linhas da tabela neste idioma.

tables[].machineinteger

Traduzidas pela máquina, sem revisão.

tables[].approvedinteger

Aprovadas.

tables[].humaninteger

Editadas por pessoa.

tables[].staleinteger

Desatualizadas: o original mudou depois da tradução.

tables[].clonedinteger

Ainda cópia do idioma padrão.

tables[].failedinteger

Com falha na tradução automática.

tables[].coverage_pctnumber

Percentual de linhas machine, approved ou human sobre o total, com uma casa decimal. É 0 quando total é 0.

Fila de revisão

GET/api/v1/admin/languages/{code}/reviewAdmin

Lista as entidades a revisar, lado a lado com o original

Para cada entidade devolve, campo a campo, o texto no idioma padrão (source) e o texto traduzido. Por padrão a fila traz o que precisa de atenção: machine, stale e failed.

Parâmetros de caminho

codestringobrigatório

Código do idioma.

Parâmetros de consulta

tablestringobrigatório

Tabela de conteúdo (product_descriptions...). Sem ela, ou com um nome desconhecido, a resposta é 400.

statusstring

clonedmachinestalehumanapprovedfailed

Mostra só este estado. Sem o parâmetro, a fila padrão (machine, stale, failed).

pageintegerpadrão: 1

Página.

per_pageintegerpadrão: 50

Itens por página, de 1 a 200. Fora disso volta a 50.

200Fila retornada

json

{
  "items": [
    {
      "entity_id": "0d9f2f5a-3b8d-4f6a-a1b4-5c4a1a6a7e10",
      "table": "product_descriptions",
      "translation_status": "machine",
      "fields": {
        "name": { "source": "Camiseta Básica", "translated": "Camiseta Básica" },
        "description": { "source": "Algodão 100%", "translated": "Algodón 100%" }
      }
    }
  ],
  "total": 1
}

Campos da resposta

items[].entity_iduuid

Id da entidade (produto, categoria...).

items[].tablestring

Tabela de conteúdo.

items[].translation_statusstring

Estado atual da tradução.

items[].fieldsobject

Um item por campo de texto da tabela (name, description, slug...), cada um com source (idioma padrão) e translated.

totalinteger

Total de entidades na fila, em todas as páginas.

Aprovar traduções

POST/api/v1/admin/languages/{code}/review/approveAdmin

Marca entidades como aprovadas

Muda o estado das entidades informadas para approved. Aprovadas, elas deixam de ser retraduzidas pelos jobs (a menos que include_approved seja true).

Parâmetros de caminho

codestringobrigatório

Código do idioma.

Corpo da requisição

tablestringobrigatório

Tabela de conteúdo.

entity_idsarrayobrigatório

Ids das entidades (strings UUID). Lista vazia não faz nada e devolve updated: 0.

200Aprovadas

json

{ "updated": 1 }

Retraduzir itens

POST/api/v1/admin/languages/{code}/review/retranslateAdmin

Retraduz entidades específicas

Refaz a tradução automática só das entidades informadas. Diferente de /translate, não cria job: a resposta 202 sai logo e a retradução segue em segundo plano, sem como acompanhar. Confira o resultado depois, na fila de revisão. Ela sobrescreve o texto atual das entidades, mesmo que estejam aprovadas.

Parâmetros de caminho

codestringobrigatório

Código do idioma.

Corpo da requisição

tablestringobrigatório

Tabela de conteúdo.

entity_idsarrayobrigatório

Ids das entidades a refazer.

A resposta é 202 Accepted, sem corpo.

Erros

Status	Quando	Corpo
400	Tabela ausente ou desconhecida; corpo inválido	`{"error":"failed to list review queue","detail":"unknown table \"\""}` (fila) ou `{"error":"failed to approve","detail":"unknown table \"x\""}` (aprovar)
401	Sem token ou token expirado	`{"error":"missing authorization header"}`
403	Sem o privilégio `manage_settings`	`{"error":"insufficient privileges","required":"manage_settings"}`
422	Sem provedor de IA configurado (retraduzir)	`{"error":"provider_not_configured"}`
500	Falha interna ao calcular a cobertura	`{"error":"failed to compute coverage","detail":"..."}`

Veja também

API atual/Referência completa/Idiomas

Cobertura e revisão

Mede quanto do catálogo já foi traduzido e revisa, aprova ou retraduz o que a máquina produziu.

Cobertura por tabela

GET/api/v1/admin/languages/{code}/coverageAdmin

Cobertura da tradução por tabela de conteúdo

Conta, para cada tabela de conteúdo, quantas linhas existem no idioma e em que estado de tradução estão. Tabelas que não existem na loja são omitidas.

Parâmetros de caminho

codestringobrigatório

Código do idioma.

200Cobertura calculada

json

{
  "language": "es",
  "tables": [
    {
      "table": "product_descriptions",
      "total": 136,
      "machine": 100,
      "approved": 10,
      "human": 2,
      "stale": 4,
      "cloned": 20,
      "failed": 0,
      "coverage_pct": 82.4
    }
  ]
}

Campos da resposta

languagestring

Idioma consultado.

tables[].tablestring

Nome da tabela de conteúdo.

tables[].totalinteger

Linhas da tabela neste idioma.

tables[].machineinteger

Traduzidas pela máquina, sem revisão.

tables[].approvedinteger

Aprovadas.

tables[].humaninteger

Editadas por pessoa.

tables[].staleinteger

Desatualizadas: o original mudou depois da tradução.

tables[].clonedinteger

Ainda cópia do idioma padrão.

tables[].failedinteger

Com falha na tradução automática.

tables[].coverage_pctnumber

Percentual de linhas machine, approved ou human sobre o total, com uma casa decimal. É 0 quando total é 0.

Fila de revisão

GET/api/v1/admin/languages/{code}/reviewAdmin

Lista as entidades a revisar, lado a lado com o original

Para cada entidade devolve, campo a campo, o texto no idioma padrão (source) e o texto traduzido. Por padrão a fila traz o que precisa de atenção: machine, stale e failed.

Parâmetros de caminho

codestringobrigatório

Código do idioma.

Parâmetros de consulta

tablestringobrigatório

Tabela de conteúdo (product_descriptions...). Sem ela, ou com um nome desconhecido, a resposta é 400.

statusstring

clonedmachinestalehumanapprovedfailed

Mostra só este estado. Sem o parâmetro, a fila padrão (machine, stale, failed).

pageintegerpadrão: 1

Página.

per_pageintegerpadrão: 50

Itens por página, de 1 a 200. Fora disso volta a 50.

200Fila retornada

json

{
  "items": [
    {
      "entity_id": "0d9f2f5a-3b8d-4f6a-a1b4-5c4a1a6a7e10",
      "table": "product_descriptions",
      "translation_status": "machine",
      "fields": {
        "name": { "source": "Camiseta Básica", "translated": "Camiseta Básica" },
        "description": { "source": "Algodão 100%", "translated": "Algodón 100%" }
      }
    }
  ],
  "total": 1
}

Campos da resposta

items[].entity_iduuid

Id da entidade (produto, categoria...).

items[].tablestring

Tabela de conteúdo.

items[].translation_statusstring

Estado atual da tradução.

items[].fieldsobject

Um item por campo de texto da tabela (name, description, slug...), cada um com source (idioma padrão) e translated.

totalinteger

Total de entidades na fila, em todas as páginas.

Aprovar traduções

POST/api/v1/admin/languages/{code}/review/approveAdmin

Marca entidades como aprovadas

Muda o estado das entidades informadas para approved. Aprovadas, elas deixam de ser retraduzidas pelos jobs (a menos que include_approved seja true).

Parâmetros de caminho

codestringobrigatório

Código do idioma.

Corpo da requisição

tablestringobrigatório

Tabela de conteúdo.

entity_idsarrayobrigatório

Ids das entidades (strings UUID). Lista vazia não faz nada e devolve updated: 0.

200Aprovadas

json

{ "updated": 1 }

Retraduzir itens

POST/api/v1/admin/languages/{code}/review/retranslateAdmin

Retraduz entidades específicas

Parâmetros de caminho

codestringobrigatório

Código do idioma.

Corpo da requisição

tablestringobrigatório

Tabela de conteúdo.

entity_idsarrayobrigatório

Ids das entidades a refazer.

A resposta é 202 Accepted, sem corpo.

Erros

Status	Quando	Corpo
400	Tabela ausente ou desconhecida; corpo inválido	`{"error":"failed to list review queue","detail":"unknown table \"\""}` (fila) ou `{"error":"failed to approve","detail":"unknown table \"x\""}` (aprovar)
401	Sem token ou token expirado	`{"error":"missing authorization header"}`
403	Sem o privilégio `manage_settings`	`{"error":"insufficient privileges","required":"manage_settings"}`
422	Sem provedor de IA configurado (retraduzir)	`{"error":"provider_not_configured"}`
500	Falha interna ao calcular a cobertura	`{"error":"failed to compute coverage","detail":"..."}`