La API Notiondesk te permite cambiar los idiomas que admite tu centro de ayuda, elegir su idioma predeterminado y activar o desactivar la traducción automática mediante IA. Úsala para implementar un nuevo idioma en varios centros de ayuda o para mantener la configuración de idiomas sincronizada con tu propia configuración.
| Método | Camino | Alcance | Hace |
|---|---|---|---|
PATCH | /sites/{site_id}/settings/supported-languages | write | Establece los idiomas que se servirán y el idioma predeterminado. |
PATCH | /sites/{site_id}/settings/auto-translate | write | Activa o desactiva la traducción automática y establece su idioma de origen. |
Ambas rutas responden a 204 No Content. Lea el nuevo estado con GET /sites/{site_id}, como se describe en Lea sus centros de ayuda con la API Notiondesk .
Configura los idiomas que admite tu centro de ayuda.
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 | Léalo de nuevo como |
|---|---|---|---|
locales | lista de cadenas | Cada idioma que atiende el centro de ayuda, al menos uno. Cada uno debe ser uno de los available_locales del centro de ayuda. | supported_locales |
default_locale | cadena | El idioma al que recurren los lectores. Debe estar en los idiomas resultantes y no puede ser null | default_locale |
Un campo que se omita conserva su valor actual.
locales Sustituye toda la lista. Si omites un idioma, este se eliminará del centro de ayuda, junto con su configuración, como el título y la descripción de la página. Para añadir un idioma, lee primero la lista y luego envíala con el nuevo idioma añadido.supported_localesLa misma adición en JavaScript, manteniendo los lenguajes actuales:
Límites del plan
Tu plan establece cuántos idiomas puede atender un centro de ayuda. Una lista locales más larga que eso responde 403 permission_denied.
Cuando tu centro de ayuda almacena un idioma que su supported_locales no muestra, cada solicitud a esta ruta responde con un error 403 permission_denied, independientemente de lo que envíes. Esto sucede cuando:
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 }),
});- El centro de ayuda admite más idiomas de los que permite el plan, por ejemplo, después de una degradación;
- El idioma almacenado está deshabilitado;
- El idioma predeterminado no tiene configuraciones guardadas y ocupa uno de los lugares del plan.
Cambia el idioma del centro de ayuda en el panel de control. La API rechaza el cambio para proteger los idiomas que no puede mostrarte: una solicitud que solo cambiara el idioma predeterminado los eliminaría, junto con su configuración. Consulta «Compatibilidad con varios idiomas en tu centro de ayuda» .
Activar o desactivar la traducción 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 | Si las traducciones faltantes se generan automáticamente |
auto_translate_source_locale | cadena o nulo | El idioma desde el que lee la traducción automática. Debe ser uno de los supported_locales del centro de ayuda. null lo borra. |
Envía los valores booleanos JSON true o false. Los valores 0 y "false" se leen como true, lo que activa la traducción facturada.
Al activar la traducción automática, se empieza a traducir tu centro de ayuda. La primera vez, también se activa la facturación de traducciones para tu espacio de trabajo. Tu plan debe incluir la traducción automática. Descubre cómo funciona en Primeros pasos con la traducción automática mediante IA .
¿Qué facturas traducen mientras está en?
| Acción | Lo que se traduce |
|---|---|
| Agregar un idioma | El contenido del centro de ayuda, en el nuevo idioma. |
| Cualquier sincronización, programada o activada | El contenido que la sincronización cambió en el idioma de origen, y todo lo que aún no se ha traducido. |
| Sincronización de un artículo con archivos subidos a Notion | Cada idioma traducido automáticamente de ese artículo, incluso con texto sin cambios. |
Consulte la sección "Sincronizaciones de Trigger Notion con la API Notiondesk" para obtener información sobre cómo se traducen las sincronizaciones.
Errores
| Estado | Cuando | code |
|---|---|---|
| 400 | locales está vacío o contiene un idioma no disponible, default_locale es null o no está en los idiomas resultantes, auto_translate_source_locale no es uno de los idiomas del centro de ayuda, o el cuerpo tiene un campo desconocido. | validation_error |
| 403 | La clave carece del alcance write | insufficient_scope |
| 403 | Hay demasiados idiomas para tu plan, un idioma almacenado está oculto (consulta Límites del plan ), tu plan no incluye traducción automática o el creador de la clave no puede cambiar este centro de ayuda. | permission_denied |
| 404 | El centro de ayuda no existe en tu espacio de trabajo. | not_found |
Consulte Handle Notiondesk Errores de API, límites de velocidad y reintentos para obtener el envoltorio de error y los demás códigos.
Preguntas frecuentes
¿Cómo puedo añadir un idioma sin eliminar los demás?
Lee la sección supported_locales del centro de ayuda, agrega el nuevo idioma y envía la lista completa como locales. La ruta reemplaza la lista con lo que envías.
¿Qué códigos de idioma puedo usar?
Los que se encuentran en available_locales del centro de ayuda, devueltos por GET /sites/{site_id}.
¿Puedo traducir un solo artículo con la API?
No. La traducción automática se ejecuta en todo el centro de ayuda mientras está activo, y cada sincronización traduce los cambios realizados. La API la activa o desactiva y establece su idioma de origen.
¿Eliminar un idioma borra sus artículos en Notion?
No. La API nunca modifica el contenido de Notion. Eliminar un idioma impide que el centro de ayuda lo muestre y elimina la configuración del centro de ayuda para ese idioma.