[G9d] Docs site: Arabic translations, twelve new pages and the Arabic navigation (part 3) #209

Goal

G1 to G7 added twelve pages that exist only in English. Arabic pages on lousho.com are translated from the English pages (which are generated from the SDK's docs/*.md), and the site's CI fails when an Arabic page is stale or missing. After G9a the pages below are listed in ar/pending.json, so CI is green but the Arabic text is out of date. Bring them current. Plan row G9 (part of four).

Current state

Checked in E:\agent-sdk-docs at 40cb386, before G9a. This is a separate repository from the SDK: work in your own git worktree of it, branch lou-g9d-<slug>, pull request to LinuxDevil/agent-sdk-docs main (a merge deploys the site; the SDK repository's BRIEF-2 rules about worktrees, never forcing and never deleting branches, and reporting apply the same way).

• Arabic pages are ar/<slug>.mdx, one per English <slug>.mdx; the English pages are generated and must not be edited here. scripts/TRANSLATING.md has the rules (what to translate, what stays byte for byte, the glossary). ar/translations.json records the SHA-1 prefix of the English page each translation matches.
• node scripts/check-translations.mjs checks, per page: front matter with a quoted title, Arabic text present, the same number of fenced code blocks and identical bytes in each (Mermaid labels excepted), the same number of ## to #### headings, internal links under /ar/, valid heading anchors (anchors are mapped by heading position: the n-th heading of the English page is the n-th of the Arabic page), and not stale. --fix-links rewrites internal links and anchors to the Arabic ids; --record stores the hashes. G9a adds ar/pending.json: a slug listed there is skipped by every check. .github/workflows/check.yml runs npx mint validate, npx mint broken-links and the check on every pull request.
• The English pages changed in wave 1 by moving, adding and renaming headings (sections moved between pages), so a patch by heading position does not work: re-sync each page in full.

Scope

In:

• Translate these new pages into ar/<slug>.mdx (page, SDK source ticket): executor-api (G1), build-a-coding-agent (G3), mcp (G4a), hooks (G4b), triggers (G4c), migrating-to-create-agent (G5a), troubleshooting (G5b), cloudflare-workers (G6), runs, models-and-cost, stream-events, queue-and-steer (G7). Where a page is made of text moved from an existing page (mcp, hooks, triggers, cloudflare-workers, runs, models-and-cost, stream-events, queue-and-steer), take the Arabic from the old Arabic page (ar/configuration.mdx, ar/api-overview.mdx, ar/streaming.mdx, ar/deployment.mdx: the current file, or its version in git history if G9c has already rewritten it) and translate only the new text (intros, tables, new sections).
• Add each translated page to the Arabic navigation in docs.json, in the same group and position as its English entry (the Arabic group names are already there; add the ar/<slug> entries), and keep the Arabic and English navigation parallel.
• For each page: diff the English page against the version it was translated from (use git log -p -- <slug>.mdx in the docs repository) to see what moved; move the existing Arabic text of moved sections instead of retranslating; translate new and changed text following scripts/TRANSLATING.md and the glossary; keep every fenced code block byte for byte; keep the heading structure identical to the English page.
• Run node scripts/check-translations.mjs --fix-links, fix what node scripts/check-translations.mjs reports, remove the page's slug from ar/pending.json, and run node scripts/check-translations.mjs --record once all pages of this ticket pass.
• Run npx mint validate and npx mint broken-links.
  Out: pages in other tickets' lists; English pages; the comparison section (G9a); anything in the SDK repository.

Acceptance criteria

• Every page listed above has been removed from ar/pending.json, its Arabic text matches the English page's structure and content, and node scripts/check-translations.mjs exits 0 with the page checked (not pending).
• ar/translations.json records the new hashes for those pages.
• npx mint validate and npx mint broken-links pass.
• The pull request description lists the pages done and, for each, whether text was moved or newly translated; any page in the list that G9a did not leave pending is reported, not skipped silently.
• docs.json Arabic navigation has an entry for each of the twelve pages and parses as JSON; each page sits in the same group and position as its English entry.

Live test

None: this ticket spends nothing.

Dependencies

G9a (regenerated English pages, ar/pending.json, English navigation). Independent of G9b and G9c (see the note in G9c); all three edit ar/pending.json and ar/translations.json, and G9d also edits docs.json: rebase and keep both sides.

Notes for the implementer

• Use the terms of the glossary on every page; where the glossary has no term, follow the first-use rule (Arabic term with the English in parentheses) and add the term to the glossary table in scripts/TRANSLATING.md if more than one page uses it.
• Code blocks, inline code, link targets, error codes and product names stay as they are.
• If the English pages of your list changed after G9a (a later SDK sync), run npm run sync again first; do not translate a stale page.
• Do not translate changelog (it is exempt).

Round 2 ticket G9d. Before starting, read the agent brief (worktree rules, verification list, live-test budget) and the plan. One ticket is one pull request; put Closes #<this issue> in it.