VenddorDocumentação API
API atualAPI legada
Guia rápidoReferência completa
Carregando índice…
API atual/Referência completa

Idiomas

Como a loja habilita idiomas, edita os textos da interface e traduz o catálogo, com o mapa de todas as rotas.

Uma loja Venddor pode atender clientes em vários idiomas. O administrador escolhe quais idiomas a vitrine oferece, define o idioma padrão, ajusta os textos da interface (botões, menus, mensagens) e pode pedir à plataforma que traduza o catálogo (produtos, categorias, páginas...) automaticamente. Esta seção documenta a API dessas tarefas. Todas as rotas exigem token de administrador com o privilégio manage_settings.

Pontos-chave
  • Há dois conceitos: o catálogo mestre de idiomas (compartilhado por todas as lojas) e os idiomas habilitados na sua loja. Habilitar é escolher um item do catálogo.
  • Existem dois tipos de texto traduzido: chaves da interface (por exemplo cart.checkout), editadas em Traduções da interface, e conteúdo do catálogo (nome de produto, descrição...), traduzido pela tradução automática.
  • O código do idioma segue o padrão BCP 47 e é normalizado: pt-br vira pt-BR.
  • O idioma padrão não pode ser desabilitado nem removido; troque o padrão antes.
  • Um idioma usado por um mercado ativo (módulo Markets) não pode ser desabilitado nem removido: a API devolve 409.

Como funciona

Um idioma passa por estes estados na sua loja:

No catálogo→Habilitado→Padrão
  1. Escolha no catálogo
    GET /api/v1/admin/languages/catalog lista só os idiomas que a loja ainda não habilitou. Se o idioma não existe lá, cadastre-o em POST /api/v1/admin/languages/custom.
  2. Habilite
    POST /api/v1/admin/languages. A plataforma copia o conteúdo do catálogo do idioma padrão para o novo idioma (como cloned) e semeia as traduções da interface.
  3. Traduza
    Edite chaves da interface com PUT .../translations e, para o catálogo, dispare POST .../translate e acompanhe o job.
  4. Revise
    Use a fila de revisão para aprovar ou retraduzir o que a máquina produziu.
  5. Promova a padrão (opcional)
    POST .../set-default quando o idioma estiver pronto.

Conceitos-chave

Status de uma tradução do catálogo

Cada linha traduzida do catálogo carrega um translation_status:

ValorSignificado
clonedCópia do texto do idioma padrão, ainda não traduzida. É o estado inicial ao habilitar o idioma.
machineTraduzida automaticamente, aguardando revisão.
staleEstava traduzida, mas o texto original mudou depois. Precisa traduzir de novo.
humanEditada por uma pessoa.
approvedRevisada e aprovada.
failedA tradução automática falhou depois de 3 tentativas.

Status de um job de tradução

ValorSignificado
queuedNa fila.
runningEm execução.
completedTerminou (itens individuais podem ter falhado, veja failed_items).
failedFalhou por inteiro.
canceledCancelado por você.

Nomes em camelCase

As rotas de idiomas devolvem JSON em camelCase (nameEn, isDefault), diferente de outras áreas da API. Os campos da tradução automática (job_id, done_items) usam snake_case. Respeite o formato de cada rota.

Sobrescrever nome e direção

Ao habilitar ou editar, você pode trocar para a sua loja o nome em inglês, o nome nativo e a direção do texto (LTR da esquerda para a direita, RTL para idiomas como árabe) sem alterar o catálogo mestre. Enviar texto vazio remove a sobrescrita.

Endpoints

MétodoCaminhoPara que serveAuth
GET/api/v1/admin/languagesListar idiomas da lojaadmin
GET/api/v1/admin/languages/catalogListar o catálogo disponíveladmin
GET/api/v1/admin/languages/{code}Consultar um idiomaadmin
POST/api/v1/admin/languagesHabilitar idiomaadmin
POST/api/v1/admin/languages/customCadastrar idioma novo no catálogoadmin
PATCH/api/v1/admin/languages/{code}Alterar idiomaadmin
POST/api/v1/admin/languages/{code}/set-defaultDefinir idioma padrãoadmin
DELETE/api/v1/admin/languages/{code}Remover idiomaadmin
GET/api/v1/admin/languages/{code}/translationsLer traduções da interfaceadmin
PUT/api/v1/admin/languages/{code}/translationsGravar traduções da interfaceadmin
DELETE/api/v1/admin/languages/{code}/translations/{key}Apagar uma traduçãoadmin
POST/api/v1/admin/languages/{code}/translateTraduzir o catálogoadmin
GET/api/v1/admin/languages/{code}/translate/jobs/{id}Acompanhar o jobadmin
DELETE/api/v1/admin/languages/{code}/translate/jobs/{id}Cancelar o jobadmin
GET/api/v1/admin/languages/{code}/coverageCobertura por tabelaadmin
GET/api/v1/admin/languages/{code}/reviewFila de revisãoadmin
POST/api/v1/admin/languages/{code}/review/approveAprovar traduçõesadmin
POST/api/v1/admin/languages/{code}/review/retranslateRetraduzir itensadmin

Erros comuns

  • Usar POST /languages para reativar um idioma desabilitado. A chamada é idempotente: se o idioma já tem registro na loja, devolve o registro atual (ainda desabilitado). Reative com PATCH e enabled: true.
  • Tentar desabilitar ou remover o idioma padrão. Retorna 409. Promova outro idioma antes.
  • Enviar uma direção diferente de LTR e RTL. Só esses dois valores são aceitos (em maiúsculas ou minúsculas), senão 422.
  • Disparar a tradução automática sem provedor de IA configurado. Retorna 422 com provider_not_configured e nada é enfileirado.
  • Disparar um segundo job para o mesmo idioma. Só um job ativo por idioma: o segundo recebe 409.
  • Pedir a lista de traduções sem paginar. Sem page nem per_page a resposta traz apenas as linhas já gravadas na loja, não todas as chaves da interface.
  • Esperar que DELETE de idioma inexistente seja silencioso. Retorna 404.

Próximos passos

Habilitar idioma
Escolher do catálogo ou cadastrar um novo.
Traduzir o catálogo
Jobs assíncronos de tradução automática.
Cobertura e revisão
Medir e aprovar o que foi traduzido.
Anterior
Seções do rascunho
Próxima
Listar e consultar idiomas
Nesta página
  • Como funciona
  • Conceitos-chave
  • Status de uma tradução do catálogo
  • Status de um job de tradução
  • Nomes em camelCase
  • Sobrescrever nome e direção
  • Endpoints
  • Erros comuns
  • Próximos passos