Starlight and developer tools company
Translated Starlight documentation and the duplicate pages it puts in the corpus
Starlight will not leave a hole where a translation is missing. It serves the default language content under the translated URL with a notice on it, which is a good decision for readers and a difficult one for retrieval, because the same body of text is now published at as many addresses as you have locales. A corpus built from that site contains several copies of every untranslated page, all matching the same questions equally well.
Why this pairing is its own job
The Starlight install guide covers the tag, and the developer tools company guide covers what the assistant has to know. What follows is the part that belongs to neither.
- Fallback means an untranslated page is authored once and published many times, and every copy is a real URL in the sitemap with real content behind it.
- Duplicate documents crowd retrieval. The strongest matches for a question become several copies of one page, and the genuinely different page that had the rest of the answer never gets near the top.
- Navigation labels and page titles come from translation files even where the body does not, so a copy can arrive with a translated title above default language prose, which is confusing in a citation line.
- A developer tools company translates in a predictable order: the getting started material first, the reference last. The reference is what people ask about, so the pages with the most duplicates are the pages with the most questions attached.
What changes about the install here
<script src="https://cdn.askably.xyz/w.js" data-key="pk_live_YOUR_KEY" defer></script>The tag is the same one on the Starlight guide. Everything below is about where it goes on a developer tools company site specifically.
One head entry covers every locale route
Locale routes are generated from the same configuration, so the entry you added to the integration options is emitted on all of them. There is nothing per language to install and no second key to manage.
That also means the widget appears on pages whose prose is in a language you may not have material for. Decide what you want to happen there before somebody in another market types a question and gets your refusal message in English.
Locale roots are paths, not origins
Adding languages does not add anything to the allowlist, because every locale is served from the same host. The allowlist question here is the ordinary one about your docs host and your main domain, not a per language one.
The exception is a team that serves a market from its own domain rather than from a locale path. That is a genuine second origin, it needs allowlisting, and it is also a second crawl target, at which point the duplication problem below is happening across hosts instead of across paths.
Where the answerable material lives
| The default language tree | The only complete one, and on most projects the only one worth indexing. Every page exists here, in the language your reference was written in, with no fallback notice attached. |
|---|---|
| The translated trees, complete or otherwise | Worth indexing only where a language is genuinely maintained, and then usually under its own assistant so answers and citations stay in one language. A partially translated tree indexed alongside the default one is the worst of the three options, because it contributes duplicates without contributing coverage. |
| Titles and sidebar labels, which are translated ahead of the body | These come from translation files rather than from page content, so they move independently. A citation can show a translated page title above an answer drawn from default language prose, which reads to the visitor as a mismatch even though the system did nothing wrong. |
| Reference pages generated into the docs tree at build time | Anything produced from source at build rather than written by hand is never touched by a translation workflow, so it stays in the default language under every locale URL permanently. On an API reference that is most of your page count, and all of it duplicated per language. |
The first thing to get right
Index one language, name it in the assistant's refusal wording, and exclude the other locale paths from the crawl.
Coverage is not what is missing here. The same sentences are already in the corpus several times over, and adding locales adds copies rather than answers. Cutting to one language usually improves the answers immediately, which is an unusual thing for a restriction to do.
The failure that belongs to this combination
Three copies of one page beating the page that had the answer
A reader asks something that needs two pages: the concept page and the one worked example. The concept page exists in five locales, four of them serving the same default language body. Those five copies occupy the strongest matches, the example page does not surface, and the answer arrives complete in tone and missing the part the reader needed.
It presents as a vague assistant rather than as a corpus problem, which is why it goes uninvestigated. The tell is in the citations: several links whose paths differ only by a locale segment, pointing at text that is word for word identical.
Read the citation paths on a few test questions before launch. If they differ only by locale, the corpus is competing with itself and the fix is to cut it down, not to add more material.
Before you go live
- The origin the page is served from has to be on the allowlist for that assistant, or nothing renders and the browser console says which origin was refused. An apex domain and its www are two different origins to a browser, so list both, along with any staging or preview host you want it to work on.
- Open the site as a visitor would, on the pages a developer tools company visitor actually lands on, and ask it something only your own material could answer. A widget that renders is not the same as a widget that has read anything.
Questions
- Can it answer in the reader's language from default language material?
- Treat that as a decision to make deliberately rather than a feature to rely on. What is certain is what it cites: it quotes and links the material it read, so the citations point at pages in whatever language you indexed. If a market matters enough to answer in, it matters enough to give its own maintained material and its own assistant.
- Should we index the locale that is only half translated?
- No. Half a tree means half the pages are duplicates of the default language and half are genuine translations, and nothing distinguishes them to a retrieval system. You get the duplication cost without the coverage benefit. Wait until the tree is maintained, then give it its own assistant.
- Does the fallback notice itself end up in answers?
- It can, because it is text on the page like anything else, and a reader who sees a line about missing translations quoted back at them has learned nothing useful. It is another reason to point the corpus at the default language tree, where that notice does not appear at all.
Keep reading
- Installing on StarlightUse the head option inside the Starlight integration config, giving the entry a tag of script and the loader attributes in attrs.
- Everything for a developer tools companyOn a docs site an assistant competes with search, not a phone line. Version skew, deprecations and error strings decide whether it earns its place.
- Indexing a versioned Docusaurus site without answering from the wrong releaseVersioned docs put several releases on separate paths. Which of them the crawl reads decides whether an answer is safe or an afternoon lost.
- What happens to the assistant when each release is its own MkDocs buildEvery release is deployed as its own static copy. Older ones were built before you added the override, so they carry no tag and cannot get one.
Try it on your own material
Upload a document or point it at your site, paste one line of HTML, then ask it something only your business could answer.