> ## Documentation Index
> Fetch the complete documentation index at: https://docs.holydocs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Internationalization

Translate your documentation into 24 languages using AI-powered translation with glossary support.

## 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:

**English** en
  **Spanish** es
  **French** fr
  **German** de
  **Portuguese** pt
  **Italian** it
  **Dutch** nl
  **Russian** ru
  **Japanese** ja
  **Korean** ko
  **Chinese (Simplified)** zh-CN
  **Chinese (Traditional)** zh-TW
  **Arabic** ar
  **Hindi** hi
  **Turkish** tr
  **Polish** pl
  **Swedish** sv
  **Danish** da
  **Norwegian** no
  **Finnish** fi
  **Czech** cs
  **Thai** th
  **Vietnamese** vi
  **Indonesian** id

## Setting Up

**Add Languages**

In the dashboard, go to **Settings > Languages** and add the languages you want to translate to.

    Or via the API:

    ```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" }'
    ```
  **Configure Navigation**

Add a language switcher to your `docs.json`:

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

Translate a single page or all pages:

    ```bash
    # Translate a specific page
    curl -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 pages
    curl -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" }'
    ```
  **Review Translations**

Translations appear in the dashboard under **Settings > Languages**. Each translation shows its status and can be reviewed before publishing.

## 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 term
curl -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:

| Operation | Dashboard | API |
|---|---|---|
| **Add term** | Settings > Languages > Glossary > Add Term | `POST /api/v1/projects/:id/glossary` |
| **Edit term** | Click the term in the glossary list | `PUT /api/v1/projects/:id/glossary/:termId` |
| **Delete term** | Click the delete icon next to the term | `DELETE /api/v1/projects/:id/glossary/:termId` |
| **Import CSV** | Settings > Languages > Glossary > Import | `POST /api/v1/projects/:id/glossary/import` |
| **Export CSV** | Settings > Languages > Glossary > Export | `GET /api/v1/projects/:id/glossary/export` |

Example CSV format for bulk import:

```csv
term,es,fr,ja,de
deployment,despliegue,deploiement,deployment,Bereitstellung
endpoint,endpoint,endpoint,endpoint,Endpunkt
webhook,webhook,webhook,webhook,Webhook
authentication,autenticacion,authentification,authentication,Authentifizierung
```

## Translation Status

Each page translation has one of these statuses:

| Status | Description |
|---|---|
| `pending` | Translation queued but not yet started |
| `translating` | AI translation in progress |
| `completed` | Translation finished and ready for review |
| `approved` | Reviewed and published |
| `failed` | Translation failed (retry available) |

## 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

| Plan | Languages | AI Translation |
|---|---|---|
| Free | 1 | Not available |
| Starter | 1 | Not available |
| Pro | 3 | Not available |
| Business | 10 | Available |
| Enterprise | 24 | Available |

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:

**Content Extraction**

The MDX page is parsed to separate translatable content (headings, paragraphs, list items, callout text) from non-translatable elements (code blocks, component props, URLs, file paths). Code blocks are preserved verbatim.
  **Glossary Injection**

Glossary terms are loaded and injected into the translation prompt. The LLM is instructed to use the exact glossary translations for matched terms, ensuring consistency across all pages.
  **LLM Translation**

Each translatable segment is sent to the LLM with context about the surrounding content. The model receives the source language, target language, glossary, and instructions to preserve MDX formatting.
  **Reassembly**

Translated segments are reassembled into a valid MDX page, preserving the original structure — frontmatter, component usage, code blocks, and links all remain intact.
  **Validation**

The reassembled page is validated to ensure MDX syntax is correct and no structural elements were corrupted during translation.

## Quality Assurance

Ensure translation quality with these built-in features:

**Side-by-side review**

The dashboard translation editor shows the source and translated page side by side. Reviewers can compare each section and make inline edits before approving.
  **Stale translation detection**

When a source page changes, all its translations are automatically marked as stale. The dashboard shows a badge on stale translations so reviewers know which pages need attention.
  **Translation memory**

Previously translated segments are cached and reused when similar content appears in new pages. This improves consistency and reduces translation costs for incremental updates.
  **Human override**

Any machine-translated segment can be manually overridden. Human edits are preserved across re-translations — the pipeline will not overwrite manually reviewed content unless explicitly requested.

## 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:

| Language | URL Pattern | Example |
|---|---|---|
| English (default) | `/page-path` | `docs.example.com/quickstart` |
| Spanish | `/es/page-path` | `docs.example.com/es/quickstart` |
| Japanese | `/ja/page-path` | `docs.example.com/ja/quickstart` |
| Arabic | `/ar/page-path` | `docs.example.com/ar/quickstart` |

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.