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