You can auto-translate Markdown documentation on every merge by adding a GitHub Actions step that sends changed files to a format-preserving translation API and commits the localized versions back to the repository. The hard part is not the workflow trigger; it is protecting code blocks, front matter, inline links, and tables so the translation engine never rewrites a command or breaks a fenced block. Bluente's translation API preserves Markdown structure across 120+ languages, which is what lets a docs-as-code pipeline run unattended without producing broken localized files. As of June 2026, teams shipping multilingual docs increasingly want this to happen at merge time rather than as a manual batch.
For context: Bluente is a document translation platform used by professionals in law, finance and consulting, covering 120+ languages with the source formatting preserved. For engineering and developer-experience teams, the same format-preserving engine that handles PDFs and Office files also keeps Markdown intact, which means localized docs stay in sync with the source on every commit.
Why Does Markdown Translation Break Code Blocks and Links?
Markdown translation breaks code blocks and links because a naive translator treats the entire file as prose and happily rewrites the contents of a fenced block, a variable name, or a URL. The result is documentation where the explanation is translated but the example no longer runs, or where an inline link points to nowhere because its anchor text and target got mangled.
The fix is structural awareness: the engine has to recognize fenced code blocks, inline code spans, front matter, link targets, and image references and pass them through untouched while translating only the prose around them. Bluente's engine preserves these elements during translation, so a localized README keeps every code block, badge, link, and YAML front-matter field exactly as written, and only the human-readable text changes.
How Do You Wire Translation Into a GitHub Actions Workflow?
You wire it in by adding a job that triggers on pushes to your docs directory, detects which Markdown files changed, sends them to the translation API, and commits the localized output to language-specific paths. The workflow runs on the same merge that updates the source, so the English doc and its translations never drift apart.
A typical pipeline has four steps: check out the repository, diff the changed Markdown files against the previous commit, call the translation API for each target language, and open a commit or pull request with the localized files. Because the API returns format-preserving Markdown, the committed files are ready to build with your static-site generator without a manual cleanup pass. The full API reference for wiring this up lives in the Bluente documentation.
Should You Translate on Every Commit or in Batches?
Translate on every merge to your main docs branch, because incremental translation keeps localized docs current and keeps each job small and fast. Batching translation into a periodic run saves a little overhead but reintroduces drift, where the localized docs lag the source and users on non-English versions read stale instructions.
Because most documents translate in under two minutes on average and the pipeline only processes files that actually changed, per-merge translation stays cheap and quick. Per-page pricing rather than per-word billing makes the running cost predictable, and there are no per-seat fees as the team or the number of target languages grows. For a docs site that ships changes daily, the incremental model is both fresher and easier to reason about.
How Do You Keep Product and API Terminology Consistent?
You keep terminology consistent by applying a custom glossary in the translation call, so product names, API method names, and defined terms render the same way across every page and every language. Developer docs are full of terms that must not be translated at all, such as function names and configuration keys, and others that must be translated the same way every time.
Bluente lets you define a glossary once and apply it across the whole pipeline. Terms you want left untouched stay untouched, and terms you want rendered a specific way render that way on every page. This removes the most common source of localized-doc inconsistency, where the same concept drifts into two or three different translations across a large documentation set.
Can AI Agents Call the Same Translation Step Directly?
Yes. Beyond the CI/CD pipeline, the same translation capability is available through the Bluente MCP server, so an AI agent can translate documents as a tool call inside an automated workflow. This is useful when the translation step is part of a larger agentic process rather than a fixed build pipeline, for example an agent that generates docs, translates them, and routes them for review.
The MCP server exposes format-preserving translation as a callable tool, which means an agent in a framework like Claude Desktop or a custom orchestration layer can localize content without a human in the loop. The server and integration details are on GitHub. For teams already building agentic documentation workflows, this keeps translation as one callable step rather than a separate manual stage.
Is It Secure Enough for Private Repositories and Internal Docs?
Yes. Bluente is SOC 2 Type II, GDPR, and ISO 27001 compliant, with zero data retention, automatic deletion within 24 hours, and documents that are never used to train AI models. Internal documentation often describes unreleased features and architecture, so the security posture matters even for content that will eventually be public.
Because nothing is retained and content is never used for model training, sending docs through the API on every merge does not accumulate a copy of your repository somewhere. End-to-end encryption protects content in transit and during processing, and the security pack is available ahead of any review for teams whose security process gates new dependencies in the build pipeline.
Frequently Asked Questions
Q: Will translating Markdown in CI/CD break my code blocks? No. Bluente's engine recognizes fenced code blocks, inline code, front matter, and link targets and passes them through untouched, translating only the prose, so localized files keep every example and link intact.
Q: When should the translation step run in my pipeline? Run it on every merge to your main docs branch and process only the files that changed. Incremental translation keeps localized docs in sync with the source and keeps each job small and fast.
Q: How do I stop API method names from being translated? Apply a custom glossary in the translation call. Terms you mark to leave untouched, such as function names and configuration keys, stay as written, while other defined terms render consistently across every page.
Q: Can an AI agent call Bluente translation directly instead of a build pipeline? Yes. The Bluente MCP server exposes format-preserving translation as a callable tool, so an agent can localize documents as one step inside a larger automated workflow.
Q: How fast and predictable is per-merge translation? Most documents complete in under two minutes on average, the pipeline only processes changed files, and per-page pricing keeps the running cost predictable with no per-seat fees as languages or contributors grow.
Q: Is it safe to send private-repository docs through the API? Bluente is SOC 2 Type II, GDPR, and ISO 27001 compliant with zero data retention, automatic deletion within 24 hours, and end-to-end encryption. Documents are never used to train AI models.
Related Reading
Translate Google Docs, Sheets, and Slides Without Losing Formatting
How to Automate Document Translation Workflows With AI Agents
How to Automate Fund Document Translation Without Compliance Risk
5 Ways to Automate Batch Regulatory Document Translation Workflows
Sources and Further Reading
Primary standards, regulations and specifications referenced above:
Large Scale Multilingual Translations on a Budget — practitioners describing this problem in r/machinetranslation
Last reviewed 29 August 2026. Written by the Bluente document engineering team, who build and test the format-preservation pipeline described above. We update these guides when the underlying standards, regulations or file formats change.
Start translating documents for free. Bluente preserves your formatting across 120+ languages in under 2 minutes. Try BluTranslate free — no credit card required.