feat(docs): Spanish routes for the guides, and header fixes - #24
Merged
Conversation
…itcher The switcher only appeared on /docs/api because it was the only page with a Spanish version: /es/docs and /es/docs/models answered 404. helmcode can show it everywhere because it keeps every guide in both languages. Now so can we. The Spanish guides ship as COPIES of the English ones, marked `translated: false`, and the page says so instead of passing English off as a translation. Flipping that flag as each guide is really translated is the whole remaining job, and it is content work, not code. Where the files live is not cosmetic. The obvious layout, `docs/en/…` and `docs/es/…`, would turn every entry id into `en/intro`, and SAFE_SLUG in src/lib/docsApi.ts rejects slashes: the manifest route throws on the first one, so /api/docs/manifest.json would answer 500 and the Discord bot would lose its entire knowledge base. English stays exactly where it is and Spanish goes in its own collection, so the published slugs never move. The manifest itself is untouched and keeps serving English only. Whether the bot should index Spanish too is a separate decision with its own slug design. Also in here: - The wordmark in the header now goes to nan.builders instead of the docs index. It is the brand mark, and "Guides" right beside it already covers going to the docs index. - The breadcrumb is built from the locale-stripped path: counting `/es` as a segment made every Spanish page show an extra crumb for the docs index. - Chrome strings, TOC label, search placeholder and prev/next are translated. - Every guide is now listed in the sitemap in both languages with alternates. Verified in a browser across both languages: the switcher round-trips, the notice shows only where the flag says so, breadcrumbs read correctly and the layout holds. Tests verified by mutation: reverting the breadcrumb fix, removing a Spanish guide or letting the two collections disagree on order each make the suite fail.
… notice The six guides are now real Spanish, not copies behind a warning, so the notice and the `translated` flag it depended on are gone: schema field, layout branch, style rule and route prop. What was translated is the prose, the frontmatter and the copy inside the MDX components (card descriptions, spec labels, capability lists). Left untouched: code blocks, commands, model names, endpoint paths, terminal output, image paths and the literal labels of the product UI, since those are what a reader sees on screen and translating them would send people looking for a button that does not exist. Two things surfaced while checking it in a browser rather than in the diff: - The API reference split the Spanish sidebar in two. Its nav group is not frontmatter, since it is not in either collection, so it was hardcoded to "Reference" and the Spanish nav came out with "Reference" and "Referencia" as separate sections. It now carries a label per locale. - The rate limits block at the end of models.mdx was dropped in translation. Component counts between the two files now agree. No em dashes anywhere in the Spanish text. Tests updated to the new premises: the two collections must still agree on `order`, must group their pages the same way whatever the labels say, must end up with the same number of nav groups, and no Spanish page may be byte identical to its English original. Verified by mutation, including that reverting the group label to English fails the suite.
The card had its labels as literals inside the component, so it always rendered one language regardless of the route. They were Spanish, leaked into /docs, got translated to English, and then leaked into /es/docs the other way round. Move the labels next to the numbers they label, in rateLimits.ts, and pick the locale from the route the page was rendered for, since MDX content cannot receive props from the layout. The manifest that /api/docs serves stays English: the locale defaults to 'en' and mdxToText does not pass one. Also fix a latent crash in the docs layout, where the default description read `lang` before the destructuring had bound it. Any page without a description would have thrown. The guard only looked for Spanish inside English files, which is half the problem, so it never saw this. The new tests check both directions and fail if a literal comes back into the component.
The limits card said 3,000M next to a model card that says 3.000M on the same page. Grouping is forced because es-ES leaves four-digit numbers ungrouped, which would print 3000M instead.
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
2 participants
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.
Two things reported on the deployed docs header, and the second turned out to
need real work.
The wordmark went to the docs index
Clicking the logo took you to
/docsrather than to the site. It is the brandmark, and "Guides" right beside it already covers the docs index, so it now
goes to
nan.builders.The language switcher was missing from the guides
It only appeared on
/docs/api, because that was the only page with a Spanishversion:
/es/docsand/es/docs/modelsanswered 404. helmcode shows theswitcher everywhere because it keeps every guide in both languages.
So the guides get Spanish routes. The Spanish copies ship as copies of the
English ones, marked
translated: false, and the page says so rather thanpassing English off as a translation:
Flipping that flag as each guide is really translated is the remaining job, and
it is content work rather than code.
Where the Spanish files live is not cosmetic
The obvious layout,
docs/en/…anddocs/es/…, would turn every entry id intoen/intro.SAFE_SLUGinsrc/lib/docsApi.tsrejects slashes and themanifest route throws on the first one, so
/api/docs/manifest.jsonwouldanswer 500 and the Discord bot would lose its entire knowledge base.
English therefore stays exactly where it is and Spanish goes in its own
collection, so the published slugs never move. There is a test pinning that.
The manifest is untouched and keeps serving English only. Whether the bot
should index Spanish as well is a separate decision with its own slug design.
Also in here
/esas asegment made every Spanish page show an extra crumb for the docs index.
Testing
662 tests green. Checked in a browser across both languages: the switcher
round-trips, the notice shows only where the flag says so, breadcrumbs read
correctly and the layout holds at 720px with no overflow.
Verified by mutation: reverting the breadcrumb fix, removing a Spanish guide,
or letting the two collections disagree on
ordereach make the suite fail.