Skip to content

feat(docs): support all GitHub documentation languages - #14

Merged
matcra587 merged 1 commit into
mainfrom
mc/docs-languages
Sep 21, 2026
Merged

matcra587 merged 1 commit into
mainfrom
mc/docs-languages

Conversation

@matcra587

Copy link
Copy Markdown
Owner

Description

Documentation retrieval previously accepted English pages only. Add language to list_docs and search_docs, and infer the language for get_doc from its slug or URL. All nine current GitHub Docs languages are supported; English remains the default.

Missing translations return an explicit error with a separate English call when a matching page is known. Catalogues, refresh failures and fallback search are isolated by language while page and disk cache budgets remain shared. Non-English listings expose slugs without substituting English titles. Unicode snippets and heading retrieval preserve source bytes through pagination.

Review Focus

  • Start with internal/docs/languages.go for language selection, cache keys and English alternatives, then the locale guards in client.go and apisearch.go.
  • Review cursor validation and source-byte preservation together. Their tests cover large selections, Unicode, CRLF and restart behaviour.
  • Tests account for most of this change. There are no dependency or generated-file changes; the implementation and its regression tests remain in one feature PR.

Test Procedure

  • mise run check: lint, formatting, module checks, pinned vulnerability checker and shuffled race tests passed.
  • mise run test:integration: live stdio MCP exchanges against docs.github.com passed in all nine languages. Reconstructed long pages matched independently fetched upstream bytes; non-English bodies differed from English.
  • A separate live stdio traversal exhausted every catalogue and each actions filter without duplicate slugs, fetched two native-query search results per language, followed every page and section continuation, selected localized headings and replayed page/catalogue cursors after process restart with disk-cache evidence.
  • Heading fuzzing passed 923,153 executions over 30 seconds. Controlled failures covered missing translations without English body fetches, foreign-language redirects and payloads, outages, recovery, cancellation, stale caches and cursor tampering.

Live results for the reviewed implementation:

Language Catalogue entries Workflow page bytes Live result
English (en) 3,209 225,920 Pass
Spanish (es) 3,201 257,603 Pass
Japanese (ja) 3,201 233,671 Pass
Brazilian Portuguese (pt) 3,201 255,152 Pass
Simplified Chinese (zh) 3,201 206,349 Pass
Russian (ru) 3,201 341,219 Pass
French (fr) 3,201 270,995 Pass
Korean (ko) 3,201 239,899 Pass
German (de) 3,201 287,565 Pass

Each language also returned 245 entries under the actions filter. Article bodies were sampled; this does not establish correctness for every translation. Missing-translation alternatives and induced outages were tested against controlled origins.

Pre-flight Checklist

  • Changes are limited to multilingual retrieval and its regression coverage
  • Local checks and live tests pass
  • README and tool descriptions updated

Additional Notes

Cursor format advances to version 2 because preserving source line endings changes selection offsets. Version 1 continuations return a restart error; initial tool calls and existing English cache entries remain supported.

GitHub can omit Content-Language. The server rejects declared mismatches and cross-language redirects but relies on upstream routing when no language is declared; it does not classify prose language. Draft pending maintainer validation.

@matcra587 matcra587 self-assigned this Sep 21, 2026
@matcra587 matcra587 added the enhancement New feature or request label Sep 21, 2026
@matcra587
matcra587 marked this pull request as ready for review September 21, 2026 04:10
@matcra587
matcra587 merged commit e68cf3e into main Sep 21, 2026
13 checks passed
@matcra587
matcra587 deleted the mc/docs-languages branch September 21, 2026 04:10
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant