A API Notiondesk permite que você altere os idiomas que sua central de ajuda oferece, escolha o idioma padrão e ative ou desative a tradução automática por IA. Use-a para implementar um novo idioma em várias centrais de ajuda ou para manter as configurações de idioma sincronizadas com sua própria configuração.
| Método | Caminho | Escopo | Faz |
|---|---|---|---|
PATCH | /sites/{site_id}/settings/supported-languages | write | Define os idiomas disponíveis e o idioma padrão. |
PATCH | /sites/{site_id}/settings/auto-translate | write | Ativa ou desativa a tradução automática e define o idioma de origem. |
Ambas as rotas respondem 204 No Content. Leia o novo estado com GET /sites/{site_id}, conforme descrito em Leia seus centros de ajuda com a API Notiondesk .
Defina os idiomas disponíveis na sua central de ajuda.
curl -i -X PATCH "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/settings/supported-languages" \
-H "Authorization: Bearer $NOTIONDESK_API_KEY" \
-H "nd-version: 2026-10-16" \
-H "Content-Type: application/json" \
-d '{"locales": ["en", "fr", "de"], "default_locale": "en"}'| Campo | Tipo | Notas | Leia de trás para frente como |
|---|---|---|---|
locales | lista de strings | Cada idioma atendido pela central de ajuda, pelo menos um. Cada um deve ser um dos available_locales da central de ajuda. | supported_locales |
default_locale | corda | O idioma ao qual os leitores recorrem. Deve estar nos idiomas resultantes e não pode ser null | default_locale |
Um campo que você omite mantém seu valor atual.
locales Substitui a lista inteira. Um idioma que você omitir será removido da central de ajuda, juntamente com suas configurações para esse idioma, como o título e a descrição da página. Para adicionar um idioma, leia primeiro e, em seguida, envie a lista completa com o novo idioma adicionado.supported_localesA mesma adição em JavaScript, mantendo as linguagens atuais:
Limites do plano
Seu plano define quantos idiomas um centro de ajuda pode atender. Uma lista locales maior que isso responde a 403 permission_denied.
Quando sua central de ajuda armazena um idioma que seu supported_locales não exibe, toda solicitação para essa rota responde com 403 permission_denied, independentemente do que você enviar. Isso acontece quando:
const siteId = "c74781f6-1aea-4e17-ab23-bbb8b4d174b6";
const headers = {
Authorization: `Bearer ${process.env.NOTIONDESK_API_KEY}`,
"nd-version": "2026-10-16",
"Content-Type": "application/json",
};
const site = await (await fetch(`https://api.notiondesk.so/sites/${siteId}`, { headers })).json();
const locales = [...new Set([...site.supported_locales, "de"])];
await fetch(`https://api.notiondesk.so/sites/${siteId}/settings/supported-languages`, {
method: "PATCH",
headers,
body: JSON.stringify({ locales }),
});- A central de ajuda contém mais idiomas do que o plano permite, por exemplo, após um downgrade;
- Um idioma armazenado está desativado;
- O idioma padrão não possui configurações salvas e ocupa um dos lugares do plano.
Altere os idiomas da Central de Ajuda no painel de controle. A API rejeita a alteração para proteger os idiomas que não podem ser exibidos: uma solicitação que alterasse apenas o idioma padrão removeria todos os idiomas, juntamente com suas configurações. Consulte Suporte a vários idiomas na Central de Ajuda .
Ativar ou desativar a tradução automática
curl -i -X PATCH "https://api.notiondesk.so/sites/c74781f6-1aea-4e17-ab23-bbb8b4d174b6/settings/auto-translate" \
-H "Authorization: Bearer $NOTIONDESK_API_KEY" \
-H "nd-version: 2026-10-16" \
-H "Content-Type: application/json" \
-d '{"auto_translate_enabled": true, "auto_translate_source_locale": "en"}'| Campo | Tipo | Notas |
|---|---|---|
auto_translate_enabled | booleano | Se as traduções em falta são produzidas automaticamente |
auto_translate_source_locale | string ou nulo | O idioma de onde a tradução automática lê. Deve ser um dos idiomas reservados (supported_locales) da central de ajuda. (null) limpa o idioma. |
Envie os valores booleanos JSON true ou false. Os valores 0 e "false" são lidos como true, o que ativa a tradução faturada.
Ao ativar a tradução automática, você inicia a tradução da sua central de ajuda. Na primeira vez, a cobrança de traduções para o seu espaço de trabalho também será ativada. Seu plano deve incluir tradução automática. Saiba como funciona em Primeiros passos com a tradução automática por IA .
O que a tradução de faturas faz enquanto está em andamento?
| Ação | O que é traduzido? |
|---|---|
| Adicionar um idioma | O conteúdo da central de ajuda, no novo idioma. |
| Qualquer sincronização, agendada ou acionada. | O conteúdo que a sincronização alterou no idioma de origem e tudo o que ainda não foi traduzido. |
| Sincronização de artigos com arquivos carregados no Notion. | Todas as traduções automáticas desse artigo, mesmo com o texto inalterado, foram aplicadas a todos os idiomas, mesmo aqueles com texto não alterado. |
Consulte a seção "Sincronizações do Trigger Notion com a API Notiondesk" para saber como as sincronizações são traduzidas.
Erros
| Status | Quando | code |
|---|---|---|
| 400 | locales está vazio ou contém um idioma indisponível, default_locale é null ou não está nos idiomas resultantes, auto_translate_source_locale não é um dos idiomas da central de ajuda ou o corpo tem um campo desconhecido. | validation_error |
| 403 | A chave não possui o escopo write | insufficient_scope |
| 403 | Há muitos idiomas disponíveis para o seu plano, um idioma armazenado está oculto (consulte Limites do plano ), seu plano não inclui tradução automática ou o criador da chave não pode alterar esta central de ajuda. | permission_denied |
| 404 | A central de ajuda não está disponível no seu espaço de trabalho. | not_found |
Consulte a seção sobre erros da API Handle Notiondesk, limites de taxa e novas tentativas para obter informações sobre o envelope do erro e os demais códigos.
Perguntas frequentes
Como adiciono um idioma sem remover os outros?
Leia o documento supported_locales da central de ajuda, adicione o novo idioma e envie a lista completa como locales. A rota substituirá a lista pelo que você enviar.
Quais códigos de idioma posso usar?
Os que estão no available_locales da central de ajuda, retornados por GET /sites/{site_id}.
Posso traduzir um único artigo usando a API?
Não. A tradução automática é executada em toda a central de ajuda enquanto estiver ativada, e cada sincronização traduz o que foi alterado. A API a ativa ou desativa e define seu idioma de origem.
Remover um idioma exclui seus artigos no Notion?
Não. A API nunca altera o conteúdo do seu Notion. Remover um idioma impede que a central de ajuda o exiba e remove as configurações da central de ajuda para esse idioma.