Translations API

Overview

The Translations API provides programmatic control over AI-powered documentation translations. Configure target languages, trigger translation jobs, manage glossary terms for domain-specific terminology, and track translation status across your documentation.

Base path: https://api.holydocs.com/api/v1/projects/:projectId

All translation endpoints require authentication. Language management and triggering translations both require the projects:write scope.

HolyDocs translations are AI-powered, not machine-translated. Each page is translated by an LLM that understands context, preserves MDX component structure, and respects your glossary for consistent terminology. Code blocks, component props, and URLs are preserved untranslated.

Supported Languages

HolyDocs supports 24 languages for AI-powered translation:

The source language for your documentation is auto-detected from your content. You do not need to specify it explicitly. English is the default source language.

List Languages

Retrieve the configured target languages for a project.

bash
GET /api/v1/projects/:projectId/languages

Copy as context

bash
curl "https://api.holydocs.com/api/v1/projects/$PROJECT_ID/languages" \  -H "Authorization: Bearer $HOLYDOCS_API_KEY"

bash
holydocs api get "/projects/$PROJECT_ID/languages"

ts
import { HolyDocs } from '@holydocs/sdk';const client = new HolyDocs({ apiKey: process.env.HOLYDOCS_API_KEY });const { data } = await client.translations.listLanguages(projectId);

Response

json
{  "data": {    "sourceLanguage": "en",    "targetLanguages": [      {        "code": "ja",        "name": "Japanese",        "translatedPages": 38,        "totalPages": 42,        "completionRate": 0.90,        "lastTranslatedAt": "2026-04-10T08:30:00Z"      },      {        "code": "de",        "name": "German",        "translatedPages": 42,        "totalPages": 42,        "completionRate": 1.0,        "lastTranslatedAt": "2026-04-11T02:15:00Z"      },      {        "code": "zh-CN",        "name": "Chinese Simplified",        "translatedPages": 20,        "totalPages": 42,        "completionRate": 0.48,        "lastTranslatedAt": "2026-04-08T14:00:00Z"      }    ]  }}

bash
curl "https://api.holydocs.com/api/v1/projects/proj_abc123/languages" \  -H "Authorization: Bearer hd_a1b2c3d4e5f67890a1b2c3d4e5f67890"

javascript
const response = await fetch(  'https://api.holydocs.com/api/v1/projects/proj_abc123/languages',  {    headers: {      'Authorization': 'Bearer hd_a1b2c3d4e5f67890a1b2c3d4e5f67890'    }  });const { data } = await response.json();for (const lang of data.targetLanguages) {  const pct = (lang.completionRate * 100).toFixed(0);  console.log(`${lang.name}: ${pct}% (${lang.translatedPages}/${lang.totalPages})`);}

Add Language

Add a new target language to the project. This does not trigger translation -- it configures the language as a translation target.

bash
POST /api/v1/projects/:projectId/languages

Request Body

json
{  "code": "fr",  "autoTranslate": true}

Response

json
{  "data": {    "code": "fr",    "name": "French",    "autoTranslate": true,    "translatedPages": 0,    "totalPages": 42,    "completionRate": 0.0,    "createdAt": "2026-04-11T10:00:00Z"  }}

Enable autoTranslate to keep translations up-to-date automatically. When a source page is updated and redeployed, the translation for that page is automatically re-queued. This is the recommended setting for actively maintained documentation.

Remove Language

Remove a language and all its translations from the project.

bash
DELETE /api/v1/projects/:projectId/languages/:code

Path Parameters

Response

json
{  "data": {    "deleted": true,    "code": "fr",    "pagesDeleted": 42  }}

This permanently deletes all translations for the removed language. The source content is not affected. This action cannot be undone.

Trigger Translation

Start a translation job for a specific page or all pages in a language.

bash
POST /api/v1/projects/:projectId/translate

Request Body

json
{  "language": "ja",  "scope": "all"}

json
{  "language": "ja",  "scope": "page",  "pagePath": "/quickstart"}

json
{  "language": "ja",  "scope": "stale"}

Response

json
{  "data": {    "jobId": "tr_abc123",    "language": "ja",    "scope": "all",    "pagesQueued": 42,    "estimatedDuration": 180,    "status": "queued",    "createdAt": "2026-04-11T10:00:00Z"  }}

bash
curl -X POST "https://api.holydocs.com/api/v1/projects/proj_abc123/translate" \  -H "Authorization: Bearer hd_a1b2c3d4e5f67890a1b2c3d4e5f67890" \  -H "Content-Type: application/json" \  -d '{    "language": "ja",    "scope": "all"  }'

javascript
const response = await fetch(  'https://api.holydocs.com/api/v1/projects/proj_abc123/translate',  {    method: 'POST',    headers: {      'Authorization': 'Bearer hd_a1b2c3d4e5f67890a1b2c3d4e5f67890',      'Content-Type': 'application/json'    },    body: JSON.stringify({      language: 'ja',      scope: 'stale' // Only retranslate pages updated since last translation    })  });const { data } = await response.json();console.log(`Translation job ${data.jobId}: ${data.pagesQueued} pages queued`);

Translation Scopes

List Translations

Retrieve translation status for all pages in a specific language.

bash
GET /api/v1/projects/:projectId/translations

Query Parameters

Response

json
{  "data": [    {      "pagePath": "/quickstart",      "pageTitle": "Quickstart Guide",      "language": "ja",      "status": "completed",      "translatedTitle": "\u30af\u30a4\u30c3\u30af\u30b9\u30bf\u30fc\u30c8\u30ac\u30a4\u30c9",      "sourceHash": "a1b2c3d4",      "translatedHash": "e5f6g7h8",      "wordCount": 1240,      "translatedAt": "2026-04-10T08:30:00Z",      "sourceUpdatedAt": "2026-04-09T12:00:00Z"    },    {      "pagePath": "/api/authentication",      "pageTitle": "API Authentication",      "language": "ja",      "status": "stale",      "translatedTitle": "API\u8a8d\u8a3c",      "sourceHash": "i9j0k1l2",      "translatedHash": "m3n4o5p6",      "wordCount": 890,      "translatedAt": "2026-04-05T06:00:00Z",      "sourceUpdatedAt": "2026-04-08T14:00:00Z"    },    {      "pagePath": "/webhooks",      "pageTitle": "Webhooks",      "language": "ja",      "status": "pending",      "translatedTitle": null,      "sourceHash": "q7r8s9t0",      "translatedHash": null,      "wordCount": 1560,      "translatedAt": null,      "sourceUpdatedAt": "2026-04-10T09:00:00Z"    }  ],  "meta": {    "total": 42,    "page": 1,    "perPage": 50,    "totalPages": 1  }}

Translation Statuses

A stale translation is still served to readers. HolyDocs does not hide translated content when the source changes. Instead, it flags the translation as stale so you can prioritize retranslation. Use scope: "stale" in the translate endpoint to batch-update stale pages.

Add Glossary Term

Add a term to the project glossary. Glossary terms ensure consistent translation of domain-specific terminology, product names, and technical jargon across all languages.

bash
POST /api/v1/projects/:projectId/glossary

Request Body

json
{  "term": "HolyDocs",  "description": "Product name, do not translate",  "translations": {    "ja": "HolyDocs",    "de": "HolyDocs",    "zh-CN": "HolyDocs",    "fr": "HolyDocs"  }}

Response

json
{  "data": {    "id": "gl_abc123",    "term": "HolyDocs",    "description": "Product name, do not translate",    "translations": {      "ja": "HolyDocs",      "de": "HolyDocs",      "zh-CN": "HolyDocs",      "fr": "HolyDocs"    },    "caseSensitive": true,    "createdAt": "2026-04-11T10:00:00Z"  }}

bash
curl -X POST "https://api.holydocs.com/api/v1/projects/proj_abc123/glossary" \  -H "Authorization: Bearer hd_a1b2c3d4e5f67890a1b2c3d4e5f67890" \  -H "Content-Type: application/json" \  -d '{    "term": "deployment pipeline",    "description": "The automated build and publish process",    "translations": {      "ja": "\u30c7\u30d7\u30ed\u30a4\u30e1\u30f3\u30c8\u30d1\u30a4\u30d7\u30e9\u30a4\u30f3",      "de": "Deployment-Pipeline",      "fr": "pipeline de d\u00e9ploiement"    }  }'

javascript
const response = await fetch(  'https://api.holydocs.com/api/v1/projects/proj_abc123/glossary',  {    method: 'POST',    headers: {      'Authorization': 'Bearer hd_a1b2c3d4e5f67890a1b2c3d4e5f67890',      'Content-Type': 'application/json'    },    body: JSON.stringify({      term: 'deployment pipeline',      description: 'The automated build and publish process',      translations: {        ja: '\u30c7\u30d7\u30ed\u30a4\u30e1\u30f3\u30c8\u30d1\u30a4\u30d7\u30e9\u30a4\u30f3',        de: 'Deployment-Pipeline',        fr: 'pipeline de d\u00e9ploiement'      }    })  });const { data } = await response.json();console.log(`Glossary term "${data.term}" added (${data.id})`);

Glossary Best Practices

Update Glossary Term

Update an existing glossary term's translations, context, or doNotTranslate flag. All fields are optional — unspecified fields are left untouched.

bash
PUT /api/v1/projects/:projectId/glossary/:termId

Request Body

json
{  "sourceTerm": "deployment pipeline",  "translations": {    "es": "pipeline de despliegue",    "ja": "デプロイパイプライン"  },  "context": "technical",  "doNotTranslate": false}

Response

json
{  "data": {    "id": "gl_abc123",    "sourceTerm": "deployment pipeline",    "translations": {      "es": "pipeline de despliegue",      "ja": "デプロイパイプライン"    },    "context": "technical",    "doNotTranslate": false  }}

Returns 404 NOT_FOUND if the glossary term does not exist or belongs to another project.

List Glossary Terms

Retrieve all glossary terms for a project.

bash
GET /api/v1/projects/:projectId/glossary

Query Parameters

Response

json
{  "data": [    {      "id": "gl_abc123",      "term": "HolyDocs",      "description": "Product name, do not translate",      "translations": {        "ja": "HolyDocs",        "de": "HolyDocs",        "zh-CN": "HolyDocs",        "fr": "HolyDocs"      },      "caseSensitive": true,      "createdAt": "2026-04-11T10:00:00Z"    },    {      "id": "gl_def456",      "term": "deployment pipeline",      "description": "The automated build and publish process",      "translations": {        "ja": "\u30c7\u30d7\u30ed\u30a4\u30e1\u30f3\u30c8\u30d1\u30a4\u30d7\u30e9\u30a4\u30f3",        "de": "Deployment-Pipeline",        "fr": "pipeline de d\u00e9ploiement"      },      "caseSensitive": false,      "createdAt": "2026-04-11T10:05:00Z"    }  ],  "meta": {    "total": 15,    "page": 1,    "perPage": 50,    "totalPages": 1  }}

Export Translations to Repo

Commit all translations for a given language to a new branch in the project's connected repo. Lets you turn dashboard-only translations into repo-committed files that downstream tools or teammates can review in a pull request.

bash
POST /api/v1/projects/:projectId/translations/export-repo

Request Body

json
{  "language": "ja",  "branch": "translations/ja"}

Response

json
{  "data": {    "branch": "holydocs/translations-ja-1713384000000",    "commitSha": "a1b2c3d4...",    "filesWritten": 42  }}

Behavior

• Files are written as <language>/<slug>.mdx under the project's repoPath (docs directory).
• If the branch doesn't exist, it's created from the default branch. Existing branches are reused (idempotent).
• The response includes the commit SHA — open a PR manually on GitHub to merge.
• Requires a GitHub connection on the project. GitLab export is not yet supported.
• Returns filesWritten: 0 when there are no translations for the language (no-op).

Use this endpoint to graduate AI-generated or dashboard-edited translations into your repository so they are preserved across re-deploys and visible in code review. Once exported, HolyDocs treats them as human-owned translations and will never overwrite them with AI output.

Translation Workflow

A typical translation workflow using the API:

bash
POST /api/v1/projects/proj_abc123/languages{"code": "ja", "autoTranslate": true}

bash
POST /api/v1/projects/proj_abc123/glossary{"term": "HolyDocs", "description": "Product name, do not translate"}

bash
POST /api/v1/projects/proj_abc123/translate{"language": "ja", "scope": "all"}

bash
GET /api/v1/projects/proj_abc123/translations?language=ja&status=pending

Translation Limits by Plan

"Pages per month" counts individual page translation operations. Translating 42 pages into 3 languages counts as 126 page translations. Retranslating a stale page also counts as one operation.

Error Codes