docs agent failed: generated docs in the wrong language for the repo

TL;DR

Detect the repo's documentation language before generating a word. The agent defaulted to its own preferred language and produced docs nobody on the project reads, while the README and comments were in another language. Fix: sample the README, existing docs, and comment text, detect the dominant language, and pin the writer to it.

The error

docs agent failed: generated docs in the wrong language for the repo

Steps

1. Confirm the mismatch: open the repo README and a few source comments, note their language, and compare with the generated docs. Expected: a clear language difference between existing project text and the new docs.

2. Detect the repo language programmatically: collect text from the README, docs folder, and a sample of comments, then run language detection on the combined sample. Expected: one dominant language with high confidence.

3. Store the detected language in the agent's run config and pass it explicitly to the writer step as a hard requirement, not a suggestion. Expected: the config names the target language for the run.

4. Regenerate the docs with the pinned language. Expected: new docs match the README's language.

5. Add a post-generation check: run language detection on the output and fail the build if it does not match the pinned language. Expected: future runs cannot silently switch languages.

Use this when

• generated docs are in a different language than the README
• the repo's comments and docs are non-English but the agent wrote English
• a multilingual org needs docs per repo language

Not for this skill when

• the repo is intentionally multilingual (then you need per-section language targets, not detection)
• the language is right but the terminology is wrong (a glossary issue)
• only code identifiers are English while prose is another language (that is normal; detect on prose)

Variant phrasings

• docs agent wrote English docs for non-English repo
• generated documentation wrong locale
• agent ignored repo language when writing docs
• i18n mismatch in generated reference docs

Why it happens

The model's default output language wins whenever the task does not specify one. Doc-generation prompts say "write reference docs" without saying "in Japanese", so the agent produces its default language even when every signal in the repo points elsewhere.

Edge cases

• Repos with genuinely mixed languages: detect per directory and generate per directory, or pick the README's language as canonical and note exceptions.
• Code identifiers in English with prose in another language: exclude identifiers from the detection sample.
• Detection on tiny samples: require a minimum character count before trusting the result; fall back to the README language on low confidence.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_0rqj-8XZcbmuPKbvx2xDuA