generate: --language option for the output language of the docs (#120) - #124
Merged
Merged
Conversation
Page prose, headings, tables and Mermaid labels follow the chosen language
while filenames, module-tree keys and link targets stay ASCII, so the
viewer, resume and --update keep working.
- New codewiki/src/language.py: normalize codes/names ("ja" -> Japanese),
BCP-47 tag for <html lang>, and the OUTPUT_LANGUAGE prompt directive.
English (or unset) leaves prompts unchanged.
- The language travels in agent_instructions, so every prompt that already
gets get_prompt_addition() sees it, placed first. The stale-link fix agent
now gets the instructions too.
- `generate --language`, `config agent --language`, MCP generate_docs
`language`. Both instruction merge paths share AgentInstructions.merged_with
(to_backend_config no longer drops artifact_exclude).
- metadata.json records generation_info.language; --update reuses it and
refuses an explicit --language that differs.
- The GitHub Pages viewer shows each page's first H1 as its nav title for
translated docs and sets <html lang>.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #120.
Problem
--instructions "write in Japanese"added one trailingAdditional instructions:line to English prompts. Some calls (the stale-link fix agent, for one) never saw it, so parts of the output stayed English. Asking the model to translate filenames broke the invariant that each module's.mdfilename equals its module-tree key. The result:Module docs not foundwarnings, missing-docs failures, and dead viewer links.What this adds
codewiki generate --language ja(a code or a name:ja,Japanese,vi,zh, …), pluscodewiki config agent --languageas a saved default, and alanguageargument on the MCPgenerate_docstool.<OUTPUT_LANGUAGE>directive, put first in the prompt addition. It asks for all prose, headings, tables and Mermaid labels in the target language. Code, identifiers and paths are kept as they are. Filenames, module names and link targets must never be translated.agent_instructions, so every prompt that already received custom instructions gets it: module, leaf and sub-agent prompts, overviews, and the updater leaf agent. The stale-link fix agent now receives the instructions too.metadata.jsonrecordsgeneration_info.language.--updatereuses it. It overrides the saved default and refuses an explicit--languagethat differs, pointing the user to a full regeneration instead.#heading, and<html lang>is set. Filenames stay ASCII. The viewer's own UI strings stay English for now.AgentInstructions.merged_with. Side fix:to_backend_configno longer dropsartifact_exclude.--language, leaves prompts and output unchanged. The only default-path wording change: the repo-overview artifact addendum no longer forces an English section title.Testing
tests/test_language.py(23 tests) covers normalization, prompt directive placement, the config round-trip and both merge paths, metadata, update-language resolution, the stale-fix prompt, title extraction and viewer output.test_clustering_skip.py::test_over_threshold_calls_llm_and_bad_response_falls_back, which also fails onmain(itsSimpleNamespaceconfig has nomax_tokens).claude-codeprovider, Haiku 4.5):generate --language ja --github-pages: the overview prose and Mermaid labels are Japanese,metadata.jsonhas"language": "Japanese",index.htmlhaslang="ja"and the translated title, and there are no missing-docs warnings.generate --updatewith no--language: an incremental update, and the newapply_couponsection was written in Japanese.generate --update --language vi: exits 2 with the mismatch message, before any LLM call.shop.mdinstead ofrepo.md, sooverview.mdwas missing. The directive now says to use exactly the filename named above, even when it differs from a package name. After that change, the rerun producedoverview.mdcorrectly.