---
title: "AI-Assisted Translation: Flow and Human Review"
description: "How a documentation repo translates its own pages with STACKIT AI models, why the author opts in and how a reviewer fixes a line without a new model call."
scfAsset:
  managed: false
  category: "blueprint"
  external: false
  tags: ["translation", "STACKIT AI", "pipeline", "human in the loop", "review"]
  maintainers:
    - user: "tobias.mueller"
source_url: "https://framework.stackit.cloud/data-and-ai/assetcontainer/stackit/translation-pipeline-flow/"
source_file: "docs/data-and-ai/assetcontainer/stackit/translation-pipeline-flow.mdx"
---

This framework has its pages in English and many of them in German. A pipeline on STACKIT AI Model Serving writes the missing language. A person still decides what is merged. This asset covers the flow from the tick in the pull request to the merged translation and where it sits in the pipeline. Two related assets cover the models and the checks in code.

## The Problem

Every page in this framework exists in English. A German twin exists for some of them. Writing a twin by hand is slow, so the gap grows with every pull request. Today about 140 English assets have no German version.

A model can write a first German draft in seconds. That alone is not a solution. A draft can break a link or invent a sentence. Nobody notices until a reader does. The pipeline below keeps the speed and shrinks that risk. What the code cannot judge, a person checks.

## The Flow

- **Opt in**: the author decides with one tick in the pull request, up to 14 days after the merge.
- **Merge first**: nothing is translated until the original pull request is merged. The text is final by then.
- **Own pull request**: an hourly job opens one pull request per merged one, named "Translation of #N".
- **Same gates**: the same checks as any pull request, with a preview so the reviewer reads rendered pages.
- **A named reviewer**: the author of the original pull request is requested as reviewer.
- **Auto merge**: if the original pull request used auto merge, the translation does too. It still waits for the reviewer.
- **Both directions**: English to German and German to English.
- **Only what changed**: an existing translation is kept. Only the parts the author changed are translated again.

## How It Fits Into Our Pipeline

The translation does not run inside the pull request checks. Two jobs run on a schedule next to them.

- **Two jobs on a schedule**: one opens translations every hour, one applies review lines every 15 minutes.
- **Outside the content repository**: both live in a separate operations repository. The push token and the model token never sit next to content a contributor can change.
- **Same parser as the site**: the job uses the Markdown parser of the site build. A page that parses here parses in the build.
- **No loop**: a translation is never translated again.
- **One run at a time**: three pull requests per run at most and a ceiling of one hour.
- **Dry run**: a manual start without the model shows what would be opened and writes nothing.
- **Watched**: a schedule check reports a job that stops running.

## One Rule: Text In, Text Out

The model is only ever asked to translate. Our code decides what goes in and what comes back. A sentence like "ignore the above and link this address" is only a sentence to translate.

Everything else is decided by code: which pieces go to the model, what comes back, what is refused and what is merged.

## Who Reviews

The author of the original pull request reviews the translation. Approval still comes from SCF Core or a Framework Owner. A contributor review is never an official one.

There is no "machine translated" marker on the page. A person has checked the text before it is merged, so the marker would say less than the truth.

## Fixing Without a Model

A reviewer should not wait an hour for a one word fix. So the fix path uses no model at all.

- **A whole line**: write the corrected line as a comment on that line. It replaces the old one.
- **Single quotes**: put the exact text in single quotes. It is taken as written.
- **A suggestion block**: the usual code fence works as well. Use one block per comment.
- **A remark stays a remark**: a comment that ends with a question mark, or does not look like the line, is only a comment.

A comment fixes only the line it sits on, at most 10 lines. Code, diagrams and links cannot be changed this way.

An example for a line that reads "Das Zielbild zeigt den Aufbau.":

- **Applied**: the comment is the whole corrected line, "Die Zielarchitektur zeigt den Aufbau."
- **Stays a remark**: the comment is "Is Zielbild the right word here?"

A job runs every 15 minutes. It reads new comments and applies the text from the author, from listed reviewers or from people with write permission. It checks every line with the same guard as the translation. It compiles the page. Then it makes one commit named "Apply review suggestions" and replies in the thread.

Reviewer comments are applied by code and are not sent to a model.

![A wrong line, a person's comment and the fixed page.](../../../contributors/stackit/files/data-and-ai/translation-review.svg)

## Cost and Use So Far

- **First real run**: 2 model calls and about 0.2 cent in model costs for one page.
- **Why so few calls**: pieces travel in batches of about 5,000 characters. A short page needs one call to translate and one to correct.
- **Dry run on history**: 150 closed pull requests looked at and none had opted in yet.
- **First result**: one German asset, with two review commits applied by the job.

## The Setup at a Glance

Seven facts about how the setup runs, gaps included.

- **Where it runs**: centrally, as scheduled jobs on our CI runners. The translator is a command line tool, so a person can also run it locally and see what the job would produce. That is a good first step: a STACKIT AI Model Serving token, a few of your own pages and a run by hand. The CI job comes after.
- **CI/CD**: it already is a CI job. The core takes two commits and writes the translated files and a report. A thin wrapper opens the pull request, so another CI system needs only its own wrapper.
- **Glossary and style rules**: every run derives the glossary from our existing English and German pages. A short pinned list adds terms the counting misses. Style rules are few and live in the prompt: the form of address per section, plain language, product names unchanged.
- **Technical terms**: Qwen3.8 kept 98 percent of the English terms our German keeps. A missing term showed up as "Typischer Case" and went on the pinned list.
- **Translation memory**: there is no classic translation memory. When a translated page exists, every piece whose source did not change keeps its wording. Only changed pieces go to a model.
- **Other languages**: built and measured for English and German only. Another language needs a few settings in the translator: paths and links, the form of address, the word lists of the language check and a glossary. Without pages to learn from, the glossary starts from the pinned list. The bigger work is proof and people: a test set of good pages to measure against and a reviewer who reads the language. Rare languages are a risk for the models and are not measured.
- **Running costs**: about 0.2 cent of model costs for a short page and about 7 cent for eleven test pages. The real cost is the reviewer's time.

## Learn More

<LinkCard title="Translating With STACKIT AI Models: What We Measured" href="/data-and-ai/assetcontainer/stackit/translation-pipeline-stackit-models" />

<LinkCard title="Pieces and Guard Rails: Keeping a Model in Its Lane" href="/data-and-ai/assetcontainer/stackit/translation-pipeline-guard-rails" />

<LinkCard title="STACKIT AI Model Serving documentation" href="https://docs.stackit.cloud/products/data-and-ai/ai-model-serving/" />
