Skip to content

docs(translation): delete siblings only when a correction reverses a capability claim - #319

Merged
hotlong merged 23 commits into
mainfrom
claude/pm-dispatch-objectos-ju9td1
Oct 7, 2026
Merged

docs(translation): delete siblings only when a correction reverses a capability claim#319
hotlong merged 23 commits into
mainfrom
claude/pm-dispatch-objectos-ju9td1

Conversation

@objectstack-fleet

@objectstack-fleet objectstack-fleet Bot commented Oct 7, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Part of #256

What changed

One commit, 80a7653, docs/TRANSLATION.md only (+8 / −4). It aligns the translation contract with the criterion from the ruling on #256 (comment 5989567068, letter A).

  • Rule 3. It ended "When in doubt, delete rather than leave behind." That sentence now gives the ruled line instead: an English correction that removes or reverses a capability assertion deletes that page's locale siblings in the same PR, and wording and number drift (a port number, a timing) stay with the translation pass. It links the ruling. The rule's headline and its reasoning are unchanged.
  • § Retiring a page. "Never leave a translation behind for a page that was rewritten to say something different" now reads "… rewritten to remove or reverse a capability assertion (rule 3)".

Why

Read literally, both sentences prescribed deleting a whole translated page over a changed port number. That is option B, which the ruling rejected. It also contradicts AGENTS.md step 2, which leaves stale siblings for the pass. The governed AGENTS.md PR for #256 writes the same line into step 3. This PR brings the translation contract into line with it, using the same wording.

This PR lands first. The governed AGENTS.md PR carries the closing line for #256.

Checks

Measured on 80a7653. git status was empty and the merge-base with origin/main is 94ce848.

  • Ownership gate, with the workflow's argv (git diff --name-status --no-renames origin/main...HEAD gives one line, M docs/TRANSLATION.md):
    • --actor "objectstack-fleet[bot]", variable unset as it is live: exit 0, ⚠ TRANSLATION_BOT_LOGIN is not set — ownership is not enforced yet. … This PR touches 0 translation artifact(s) and 1 other file(s).
    • The same, with TRANSLATION_BOT_LOGIN=placeholder-translator: exit 0, ✓ 1 file(s) changed, no translation artifacts touched.
    • Control, actor = the placeholder translation account: exit 1, ✗ translation PRs may only touch translation artifacts.
    • --self-test: exit 0, ✓ self-test: 21 case(s), …
  • Governed predicate, objectstack scripts/pm/check-governed-merges.mjs --test docs/TRANSLATION.md --additions 8 --deletions 4 (objectstack @ ba5927f7): exit 0, ✅ NOT governed — ordinary queue landing applies to a PR with exactly this file list. and size: 12 changed line(s) (+8 / -4) ≤ 5000.
  • Control-byte scan, grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]' over the diff and over docs/TRANSLATION.md: grep exit 1 both times (no match). A positive control holding a DEL byte matched (exit 0).
  • No gate reads docs/TRANSLATION.md as input. The scripts only mention it in comments and failure text, and readFileSync of it has 0 hits under .github, apps/docs/scripts and tools. No package changed, so no build or test is owed locally.

Acceptance notes

  • GUIDE_REV is not bumped. check-translations.mjs says to bump it when a guide change "invalidates existing output (a changed term in the glossary, a changed rule about what not to translate)". This change governs when an English PR deletes siblings. It changes nothing about how a translation is written, so no existing translation goes guide-stale.
  • Ownership & freshness will not run on this PR. Its paths filter does not include docs/**, so the ownership result above is local only. CI (build, Node floor) has no path filter and runs.
  • Out of surface, and left alone: the check-translation-ownership.mjs header and failure text name only retire/rename as the reason a human PR deletes a locale file. That stays true, but it no longer covers every case. The enforced gate already admits criterion-A deletions. Measured: an English M plus three locale D lines exits 0, and a locale M control exits 1.

Pushed head

e463447 on claude/pm-dispatch-objectos-ju9td1, a fast-forward with no force. It starts at the remote branch head 7c17974, merges origin/main @ 94ce848 (after the merge the diff against main is empty), and cherry-picks 80a7653. git diff origin/main e463447 is byte-identical to the staged branch's diff.

Generated by Claude Code

objectstack-fleet Bot and others added 23 commits October 6, 2026 10:36
@objectstack-fleet @claude
docs: SEO titles for the 67 English pages whose title tag was two wor…
7b4fd19 
…ds or fewer

Adds a `seoTitle:` frontmatter line to every English page whose built
`<title>` read as one or two words plus the ` | ObjectOS` suffix, so the
tab/result title carries the terms a reader searches for while the H1,
sidebar and breadcrumb keep the short noun (#166's mechanism).

- 67 pages: each gains exactly one line; no `title`, `description` or
  body line changes.
- Every title leads with the page's own specific term, lifted from its
  description and headings, and renders at 52–60 characters including the
  suffix (measured on the built HTML).
- The three duplicated titles (Approvals, Dashboards, Notifications —
  each used by a build/configure page and a use page) are now distinct.
- English only. Locale siblings are translation artifacts that a
  non-translator commit may not modify (AGENTS.md, Translation workflow;
  check-translation-ownership.mjs); the translation pass carries the new
  key over, and the output report lists the 163 siblings now missing it.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FeA1nwBz1ohH65dvffUGKr
@claude
Merge remote-tracking branch 'origin/main' into ff/issue-301
50f7841
@claude
docs: muted-text and code-comment contrast, phone table affordance, F…
b421fbd 
…AQ headings, title-weighted per-locale search, consistency pass

- Light-mode muted foreground to hsl(0 0% 40%); code comments recoloured in
  both shiki themes.
- Tables get an always-drawn scrollbar and a scroll-driven trailing fade.
- FAQ and License FAQ questions become headings.
- /api/search builds one locale's index on that locale's first search and
  weights title > heading > text; check-search-locales gains own-title-buried;
  smoke-docs asks /api/search in every locale with a nonce control.
- Consistency: one data-residency table, one license-validation sentence,
  ObjectSchema.create, "license" spelling, Configure title, glossary order plus
  AI seat and Position, logo to the docs home, a translated llms.txt example,
  three unsourced configure/ai claims removed (with their locale siblings),
  release-following lines pointed at a populated feed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FeA1nwBz1ohH65dvffUGKr
@claude
docs: record the measured search cold start and the smoke search requ…
c5740f9 
…ests

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FeA1nwBz1ohH65dvffUGKr
@claude
docs: state the measured contrast ratios in the theme and code-theme …
21ef209 
…comments

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FeA1nwBz1ohH65dvffUGKr
@claude
docs(views): declare views in a defineView container; list only the s…
911a174 
…ix apiMethods primitives

The Views page declared views inside a defineObject call under an
object-level `view` key. ObjectStack provides no defineObject, and
ObjectSchema.create rejects `view` as an unknown key. Its views are a
defineView container ({ list, listViews, form, formViews }, each view
bound through `data`) registered on the stack with `views: [...]`, which
both samples now show; both parse with @objectstack/spec 17.6.0.

The REST API page's allowed apiMethods values drop the eight retired ones
the spec strips at parse.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FeA1nwBz1ohH65dvffUGKr
@claude
Merge remote-tracking branch 'origin/main' into ff/issue-311
c49dc6d
@claude
fix(docs): run the awaited fumadocs-mdx write after next typegen in t…
5e666c3 
…ype-check

`next typegen` loads next.config.mjs, and fumadocs-mdx 15.0.7's createMDX()
starts init() without awaiting it (dist/next/index.js:14-20). init rewrites
every .source/*.ts with fs.writeFile (dist/core-DlDe_Eze.js:232-236), which
truncates first. typegen ends in process.exit(0), so it can exit inside that
window and leave .source/server.ts empty for tsc: TS2306, CI run 37478051451.

Running the fumadocs-mdx CLI after typegen makes the CLI, which awaits its
writes, the last writer before tsc. typegen does not read .source.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FeA1nwBz1ohH65dvffUGKr
@claude
Merge remote-tracking branch 'origin/main' into ff/issue-305
5ad14ce
@claude
docs: localize fumadocs' accessible names, mark English page-tree ent…
41a1994 
…ries, zh-Hant 404, Open-in links follow the page shown

- patches/fumadocs-ui@16.8.12.patch: the nine accessible names fumadocs-ui
  16.8.12 hard-codes in English (Open Search, Toggle Theme, Open/Collapse
  Sidebar, Copy Anchor Link, Copy/Copied Text, Toggle Menu, and Radix's
  "Main") read from its i18n context with the old literal as default. Eight
  keys are a backport of upstream 16.9.0's own names; lib/ui-text supplies
  all nine through RootProvider in every locale.
- app/[lang]/docs/layout.tsx: page-tree entries (sidebar, breadcrumb,
  prev/next footer) for pages a locale has no translation of carry
  lang="en", using the docs page's own translatedLocales detection.
- app/not-found.tsx: the 404 copy moves into lib/ui-text (notFound), so the
  zh-Hant string is generated from zh-Hans by gen-zh-hant and checked by
  --check like every other Traditional string.
- Open in ChatGPT / Claude on a translated page sends the assistant to the
  translated page itself; English pages and fallbacks keep the English .mdx.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FeA1nwBz1ohH65dvffUGKr
@claude
Merge remote-tracking branch 'origin/main' into ff/issue-307
c47c544
@claude
docs: make the views and flows code samples parse with @objectstack/s…
69f7f1e 
…pec 17.7.0

views.mdx: every list-view fragment carries its required top-level
columns, fontWeight is a string, the list view types table states the
required keys the spec declares, and each fragment says what it omits.

flows.mdx: every sample is rewritten from the old trigger/steps shape to
FlowSchema's nodes and edges. Email goes through a notify node with
channels: ['email']; requires lists automation and triggers.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FeA1nwBz1ohH65dvffUGKr
@claude
Merge remote-tracking branch 'origin/main' into ff/issue-308
9709c50
@claude
docs: a main landmark, a language switcher named by its text, a decor…
7c161c3 
…ative GitHub icon, code blocks off the landmark list, a localized Open-in prompt

axe 4.14.0 reported four failures on every docs page in every locale,
English included (#308):

- landmark-one-main: the docs layout has no main landmark. DocsPage passes
  its other props to the article it renders, so the docs page sets
  role="main" there; no patch needed.
- label-content-name-mismatch: the language switcher shows the current
  language but was named "Choose a language" only. It is now named
  "English — Choose a language", "Deutsch — Sprache wählen", visible text
  first, both halves from the i18n context.
- svg-img-alt: the GitHub icon was an svg role="img" with no name inside a
  link already named "GitHub"; it is aria-hidden now.
- landmark-unique: every code block's scroll viewport was an unnamed
  role="region". The role goes; tabIndex 0 stays for keyboard scrolling.

The last three are hunks added to patches/fumadocs-ui@16.8.12.patch; its
header says why each is a hunk and not a slot, and what an upgrade must
re-check. None of the three is fixed upstream as of 16.16.2.

The "Open in ChatGPT / Claude" prompt sentence was English in every locale.
It is now the ui-text key pageActionsOpenInLLMPrompt, upstream 16.9.0's key
name, placeholder and English, translated in six locales and generated for
zh-Hant. ui-text's table() now also holds every locale's placeholders to
English, so a translation that drops {url} fails the build.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FeA1nwBz1ohH65dvffUGKr
@claude
ci: read the built pages for English chrome names and unmarked page-t…
cc14430 
…ree entries

#298 and #305 made two promises about every localized docs page that no
gate checked afterwards: no control is named in English, and every
page-tree entry for an untranslated page carries lang="en". The locale
surface gate now reads them off the prerendered HTML under
apps/docs/.next/server/app/<locale>/, script bodies (the RSC payload)
skipped:

- english-chrome-name: an accessible name (aria-label, title, alt,
  placeholder, svg title, .sr-only text) on a localized page that is one of
  the English pages' names, outside lang="en". The English set is read off
  the built English pages, minus GitHub and www.objectos.ai.
- untranslated-entry-unmarked: a sidebar item or previous/next card for a
  page the locale has no source file for, whose text does not resolve to
  lang="en". The oracle is the content tree, not the app's detection.
- translated-entry-marked-english: the over-marking direction.

Guards keep it from passing over nothing (a page missing from a locale's
build, no English name to compare, no entry of a kind recognised in a
locale), and a live control feeds both #305 shapes, built from the run's
real oracle values, through the same reader on every run. Ten self-test
cases, and the control shown red with a reader blinded to names or to lang.

On the HTML main built at cec227a it reports 6239 English names and 5974
unmarked entries; on #305's tree, 0 and 0. No ci.yml change: the existing
Locale surface step runs the gate after the build, and pnpm turbo run test
runs its self-test.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FeA1nwBz1ohH65dvffUGKr
@claude
docs: the docs page's table-of-contents bar is not a second banner
77ad6ba 
Below 1280px fumadocs-ui 16.8.12 shows the page's table of contents as a
bar rendered in a <header> outside every sectioning element, so the page
had two banner landmarks: the site header (#nd-subnav) and this bar. axe
4.14.0 at 390px reported landmark-unique and landmark-no-duplicate-banner on
all 48 runs of the #308 sample (8 sections, en/zh-Hans/de, light/dark), on
the tree that already carried the other #308 fixes. The bar is a disclosure
for the page's headings, so the patch renders it as a <div>; no CSS selects
header by element, and the 390px screenshots do not change. Upstream 16.16.2
still renders it as a <header>.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FeA1nwBz1ohH65dvffUGKr
@claude
docs: the heading-anchor and code-copy buttons keep their own languag…
5a07fbc 
…e inside an English body

#305 localized the names of the heading-anchor and code-copy buttons. On
a fallback page both buttons sit in the page body, which #298 marks
lang="en", so "Ankerlink kopieren" was read with English rules: WCAG 3.1.2,
the inverse of what #305 fixed. On main at cf449fa that was 520 + 115
names per Latin-script locale over 55 fallback pages, and 336 + 58 in
zh-Hans and zh-Hant over 31.

Both buttons now take locale from the useI18n() they already read and
render it as their own lang (patches/fumadocs-ui@16.8.12.patch, the two
#305 hunks). On a page in the route locale this repeats what html lang
says; inside an English body it keeps the name in its own language.

check-locale-surface.mjs gains the inverse rule,
localized-name-marked-english: one of a locale's own names (read off its
built pages, the names that resolve to the locale, minus the English set)
inside a lang="en" region with no lang of its own fails. Two self-test
cases (red as #305 shipped it, green through an inherited lang), the
fixture body now carries a localized anchor button with its own lang, and
the live control feeds the inverse shape too, shown red with a reader
blind to lang on names.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FeA1nwBz1ohH65dvffUGKr
@claude
ci: the built-pages guard counts docs pages only
fa2390f 
The "nothing built" guard in check-locale-surface.mjs fired artifact-missing
only when no locale directory held any HTML at all. The legal pages and the
locale roots live in the same directories, so a build (or a fixture tree)
holding them but no docs page fell through to one docs-page-html-missing per
page plus the blind-reader guards. #312 adds legal-page fixtures to every
self-test case, and with them this file's "docs pages not built" case read
exactly that way. Measured on this tip with #312's own two commits applied in
memory (git merge-tree --merge-base 4da46c5): before this change 1 self-test
case failed, after it 48 cases over 25 rules pass. The guard now asks whether
any <locale>/docs page was built.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FeA1nwBz1ohH65dvffUGKr
@claude
Merge remote-tracking branch 'origin/main' into ff/issue-312
f8920d5
@claude
docs: legal pages mark their English fallback lang="en" with the noti…
482ff8f 
…ce; zh-Hant generated from zh-Hans

- privacy and terms on de, ja, es, fr and ko: the English entry is marked
  lang="en" (title, date, body, back link) and introduced by the #298 notice
  (ui-text notTranslated) in the route locale. en and zh-Hans render as before.
- The zh-Hans entry of each page moves, unchanged, into a zh-Hans.json beside
  it; gen-zh-hant converts it to zh-Hant.json like lib/ui-text, so
  /zh-Hant/privacy and /zh-Hant/terms show Traditional text and gen-zh-hant
  --check covers it. contentLocales, hreflang and the sitemap gain zh-Hant.
- check-locale-surface: STATIC_PAGES lists zh-Hant, and three rules read the
  built legal pages (legal-english-unmarked, legal-translation-shows-english,
  legal-page-unread), with self-test cases.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FeA1nwBz1ohH65dvffUGKr
@claude
docs: legal pages render an article inside HomeLayout's main, not a s…
7c17974 
…econd main

HomeLayout already renders main#nd-home-layout around its header and the page,
so the page's own main was a nested, duplicate landmark on /privacy and /terms
in every locale (axe: landmark-no-duplicate-main, landmark-main-is-top-level,
landmark-unique). Same classes, so nothing moves on screen. The
check-locale-surface legal fixture now mirrors that structure.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FeA1nwBz1ohH65dvffUGKr
@claude
Merge remote-tracking branch 'origin/main' into ff/issue-256-p3
0dd5019
@claude
docs(translation): delete siblings only when a correction reverses a …
e463447 
…capability claim

Rule 3 ended "When in doubt, delete rather than leave behind", and the
Retiring a page section told authors never to leave a translation behind
for a page "rewritten to say something different". Read literally, both
delete a whole translated page over a changed port number, which
AGENTS.md step 2 and the new step 3 say stays with the translation pass.

Both now state the ruled line: an English correction that removes or
reverses a capability assertion deletes the page's locale siblings in
the same PR, and wording and number drift stay with the pass. Rule 3
links the ruling. GUIDE_REV is not bumped: no existing translation
output becomes invalid.

Co-Authored-By: Claude <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01FeA1nwBz1ohH65dvffUGKr
@objectstack-fleet objectstack-fleet Bot mentioned this pull request Oct 7, 2026
Closed
@objectstack-fleet
objectstack-fleet Bot marked this pull request as ready for review October 7, 2026 02:33
@hotlong
hotlong merged commit dc8213d into main Oct 7, 2026
3 checks passed
This was referenced Oct 7, 2026
Merged
Closed
Merged
@objectstack-fleet objectstack-fleet Bot mentioned this pull request Oct 7, 2026
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

@hotlong hotlong

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@hotlong @claude