Internationalization

Overview

HolyDocs provides an AI-powered translation pipeline that can translate your documentation into 24 languages. Translations are generated using LLMs with domain-specific glossary support to ensure technical terms are translated correctly.

Supported Languages

HolyDocs supports translation to these 24 languages:

Setting Up

bash
curl -X POST "https://api.holydocs.com/api/v1/projects/PROJECT_ID/languages" \  -H "Authorization: Bearer YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "language": "es" }'

json
{  "navigation": {    "languages": [      { "code": "en", "name": "English", "url": "/" },      { "code": "es", "name": "Espanol", "url": "/es" },      { "code": "ja", "name": "Japanese", "url": "/ja" }    ]  }}

bash
# Translate a specific pagecurl -X POST "https://api.holydocs.com/api/v1/projects/PROJECT_ID/translate" \  -H "Authorization: Bearer YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "language": "es", "page": "/quickstart" }'# Translate all pagescurl -X POST "https://api.holydocs.com/api/v1/projects/PROJECT_ID/translate" \  -H "Authorization: Bearer YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{ "language": "es" }'

Dashboard Translations tab

Open a project and click Translations in the left sidebar (under Manage). From here you can:

• Add a language — pick from 24 supported locales. The language is appended to docs.json automatically and the language switcher is populated.
• Review per-page status — each page in the language shows an AI, Reviewed, Outdated, Pending, or Failed badge.
• Edit translations inline — side-by-side source vs. translation with Save, Revert, Approve, and AI retranslate. Edits stay in HolyDocs; your repo is not touched unless you explicitly export.
• Manage glossary terms — add technical terminology, per-language translations, and doNotTranslate flags. Applied to every AI translation.
• Import / Export — download an XLIFF 1.2 file for offline translators, or upload one back. Also a one-click "Push to branch" that commits <lang>/*.mdx to a new branch in your repo so you can open a PR.

Repo-committed language folders

If your repo already contains top-level folders like es/, ko/, or pt-BR/ (common with legacy Mintlify migrations), HolyDocs auto-detects them on every build:

• Files are ingested as human-owned translations (translator: human, status: reviewed).
• AI translation will never overwrite a human row. Source-changed rows are marked outdated but their content is preserved.
• Detected languages are automatically added to i18n.languages in docs.json if not already configured.

If a top-level folder accidentally matches a supported language code (e.g., a product area literally named de), opt out:

json
{  "i18n": {    "defaultLanguage": "en",    "languages": ["en"],    "ignoreDirs": ["de"]  }}

Storage

• Repo-committed translations stay the source of truth — re-ingested on every deploy.
• Dashboard-only translations (AI-generated or manually added in the UI) are stored in HolyDocs (D1 + KV). Your repo stays clean. Use Push to branch to export them if you want them in git.

Glossary

Define domain-specific terms to ensure consistent translation across all pages:

bash
# Add a glossary termcurl -X POST "https://api.holydocs.com/api/v1/projects/PROJECT_ID/glossary" \  -H "Authorization: Bearer YOUR_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "term": "deployment",    "translations": {      "es": "despliegue",      "ja": "deployment",      "fr": "deploiement"    }  }'

Glossary terms are injected into the translation prompt to ensure technical terms are translated consistently. For brand names and product names, add them to the glossary with the instruction to keep them untranslated.

Glossary Management

The glossary is managed per project and applies to all target languages. You can manage it from the dashboard or via the API:

Example CSV format for bulk import:

csv
term,es,fr,ja,dedeployment,despliegue,deploiement,deployment,Bereitstellungendpoint,endpoint,endpoint,endpoint,Endpunktwebhook,webhook,webhook,webhook,Webhookauthentication,autenticacion,authentification,authentication,Authentifizierung

Translation Status

Each page translation has one of these statuses:

Incremental Translation

When you update a page in the source language, HolyDocs detects the change and marks the corresponding translations as stale. You can:

• Automatically re-translate stale pages
• Manually review and update translations
• Receive notifications when translations become stale

Requirements

AI-powered translation is available on Business and Enterprise plans. Pro plans can add multiple languages but must provide translations manually or via external tools.

Translation Pipeline (Technical Detail)

The AI translation pipeline processes pages through several stages to ensure quality:

Quality Assurance

Ensure translation quality with these built-in features:

RTL Language Support

HolyDocs supports right-to-left (RTL) languages including Arabic (ar). When a reader switches to an RTL language:

• The entire page layout mirrors automatically (sidebar on the right, content flows right-to-left)
• Text alignment switches to right-aligned
• Navigation arrows and icons are mirrored
• Code blocks remain left-to-right (LTR) as code is always LTR
• Tables maintain their structure with RTL text flow within cells

RTL support is handled automatically — no additional configuration is required. The renderer detects the language direction from the locale code and applies the appropriate CSS direction and dir attributes.

RTL support applies to the rendered documentation site. The dashboard editor always uses LTR layout regardless of the translation language.

URL Structure

Translated pages are served under a locale prefix:

The language switcher in the navigation automatically generates the correct URL for each available language. Search results are scoped to the reader's currently selected language.