Locale fallback policy
How AACSearch docs handle missing translations across en, de, es, fr and ru. Defines the EN floor, RU parity rule, and how stub pages are marked.
AACSearch ships docs in five locales: en, de, es, fr, ru. The locale switcher always points at a real page — it never resolves to a 404. This page documents how that guarantee is enforced and what readers see when a translation is not yet ready.
The three tiers
| Tier | Locale | Policy |
|---|---|---|
| 1 | en | Source of truth. Every page exists here first. |
| 1 | ru | Policy floor (Invariant 10). Every page in /en/** MUST exist at the same path in /ru/**. CI fails on a gap. |
| 2 | de, es, fr | Best-effort. Missing files are auto-stubbed from EN with [TODO i18n — see issue #76] on the description and tracked in CI as warnings. |
The split is intentional. RU is the largest non-English audience for the product and the only locale with a written compliance/billing surface that demands literal accuracy. de/es/fr are SEO + reading-time wins; falling back to EN content for them is acceptable until a translation pass runs.
What a stub looks like
When de/es/fr lack a translation, the file at the same path ships with the
EN body and a [TODO i18n — see issue #76] token appended to the
description. The body text is in English but the page is reachable —
the locale switcher resolves, search indexes the canonical URL, and the
TODO marker is greppable for future translation runs.
---
title: Streaming responses
description: [TODO i18n — see issue #76] How to stream long-running…
---You can find every stub with:
rg -l '\[TODO i18n' apps/docs/content/docs/{de,es,fr}What we never do
- 404 on locale switch. The switcher is a navigation contract. A locale must never break a working URL.
- Hide stub pages. They participate in the sidebar, sitemap and search index. The TODO marker is the only signal that they need a translation pass.
- Translate the URL slug. Paths are stable across locales — only the
body text varies. The English slug stays.
/ru/security/api-keysand/en/security/api-keysresolve to the same concept.
When the floor moves
Adding RU is mandatory for any new EN page. If a PR adds
apps/docs/content/docs/en/foo/bar.mdx, the same PR must add
apps/docs/content/docs/ru/foo/bar.mdx. CI gate
(apps/docs/scripts/check-locale-parity.py) enforces this — it treats
missing RU files as errors and de/es/fr as warnings.
If you can't write the RU translation yourself: stub the RU file from EN
with [TODO i18n — see issue #76] and open a follow-up task tagged
i18n. The page is still real, just with a visible debt marker.
Internal links inside docs
All internal links use locale-relative paths (/reference/feature-status,
not /en/reference/feature-status). The Fumadocs MDX layer rewrites them
to the active locale when rendering, so the same source link works from
any of the five locale routes without breaking on switch.
When in doubt, link to the EN slug — Fumadocs handles the rest.
Issues tracking the policy
- #76 — Enforce RU/EN docs parity and locale-safe links (this policy)
- #74 — Glossary and canonical term translations
- #64 / #67 — Docs quality gates and CI
Positioning guide
Canonical positioning for AACSearch OS. Use this page to keep blog posts, comparison pages, marketing copy and case studies aligned with the Search Operating System framing.
Glossary
Canonical AACSearch OS terminology with locked EN ↔ RU translations. The vocabulary the docs, marketing, dashboard and SDKs all resolve to. Don't translate brand terms; do translate concepts.