---
title: Translate a MkDocs Site with AI | Smartcat
description: Translate your MkDocs site with AI and review it in context. Install via a theme override for the head block.
canonical: https://www.smartcat.com/integrations/mkdocs/
language: en
updated: 2026-11-16
---

# Translate a MkDocs Site with AI | Smartcat

## Translate your MkDocs site with AI

Add the Smartcat website snippet to your MkDocs project once, deploy it through your normal pipeline, and review translations in Smartcat before you publish a language.

- [Start free trial](https://smartcat.com/sign-up)

- [Book a demo](https://www.smartcat.com/book-a-demo/?mkdocs)

## How to add Smartcat to MkDocs

Create a Smartcat website project from your published MkDocs URL and choose the target languages.

Install the generated Smartcat snippet through a theme override for the head block (extra_javascript loads assets only).

Deploy the change and open the published site to confirm the snippet is present.

Review the translations in Smartcat’s visual editor and publish the languages that are ready.

## Translate a MkDocs site without editing generated HTML

Keep the integration in your MkDocs source configuration. extra_javascript loads JavaScript assets, while a theme override may be needed when the supplied installation requires head markup. With Material for MkDocs, use the supported template extension rather than modifying the installed theme package.

Rebuild and deploy, then review a guide with navigation, admonitions, and code examples. A translated warning should preserve its severity, and a command example should remain executable. Website translation does not produce a second set of Markdown sources.

## What changes for visitors, and what stays in MkDocs

Website translation changes the published reading experience. It does not create translated source files, message catalogs, or locale builds in your MkDocs repository.

## Review before a language goes live

Machine translation gives you a fast first draft. In Smartcat’s visual editor you see each translated string on the page, shorten headings that run long on mobile, and keep product and brand names consistent with a glossary. Assign a reviewer when a page needs approval, and publish only the languages that are ready.

## Frequently asked questions

### Can I paste HTML script tags into extra_javascript?

extra_javascript is an asset configuration, not a free-form HTML head field. Follow its supported structure and use a theme override when actual markup is required.

### Can I edit translations before publishing?

Yes. Refine and confirm the wording in Smartcat’s visual editor, then publish the languages that are ready.

### What happens when I add a new page in MkDocs?

New text follows the Smartcat project’s selected translation mode. Choose reviewed translations when every new page requires approval; automatic modes can translate newly encountered text. Neither mode changes your source content in MkDocs.

Publish your MkDocs site in more languages

Install the snippet once, review the translations in context, and publish the languages your audience needs. See all [website integrations](https://www.smartcat.com/integrations/category/website-translation/) or read how the [Website Translator](https://www.smartcat.com/website-translator/) works.

- [Start free trial](https://smartcat.com/sign-up)
