Rework translate skills into one flow with proofreading and review

.agents/skills/proofread/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: proofread
+description:
+  Fixes basic typos in English docs pages without asking (spelling, doubled
+  words, punctuation, stray characters, admonition syntax) and reports anything
+  else that looks wrong. Never changes meaning, code, links, or app names. Does
+  not commit or open a PR. Use before translating, after editing a page, or to
+  sweep a section for typos.
+---
+
+# Proofread
+
+Fix basic typos in English pages in `docs/`, and report the rest. The scope is
+one page, one folder under `docs/`, or one sidebar category. With no scope,
+proofread the pages this branch changes. Never proofread `adaptors/packages/` or
+anything in `i18n/`.
+
+A fix here is safe to make without asking because it cannot change what a page
+says. Anything that could goes to a person.
+
+## Fix without asking
+
+- A misspelled word, or a word written twice.
+- A missing full stop, a doubled punctuation mark, or an unmatched bracket or
+  quote.
+- British spellings and "adapter", which `STYLE.md` rules out, except in code or
+  names.
+- A stray character, or an admonition written against `STYLE.md`: `::: tip` for
+  `:::tip`, a closing `:::note` for `:::`, or a missing blank line inside the
+  colons. Report an admonition with no closing `:::`, since where it ends
+  changes what it holds.
+
+Change only the characters that are wrong, so the diff shows just the fix.
+
+## Never touch
+
+- Code blocks, inline code, link targets, and numbers. A typo in link text is
+  fine to fix.
+- The names of things in the app, even when they look misspelled. Check the
+  English in the Lightning code (see `AGENTS.md`) before you report one.
+- Front matter.
+
+Never delete a line, even one that looks like a mistake. A line that seems out
+of place in an example may be there on purpose.
+
+## Report the rest
+
+Anything else that looks wrong goes in the report, not the page: an unclear
+sentence, a wrong fact, a broken rule in `STYLE.md`, or an app name in the wrong
+form.
+
+## Finish
+
+Do not run Prettier; whoever commits the fixes formats them first. Report in the
+chat, in this order, placing each item by its page URL (such as
+`http://localhost:3000/documentation/build/triggers`) and section heading:
+
+1. **Needs a decision.** The sentence in full, what looks wrong, and the fix you
+   would make.
+2. **Fixed.** Each sentence before and after, in full, with the changed words in
+   bold.
+3. **Translations affected.** Translated pages of the pages you changed. They
+   show as stale in `translate/status.js` until the next `/translate`, which
+   usually only needs to update their hash.
+
+Do not commit or open a PR. When you were called by another skill, return the
+report to it. To open a PR from a sweep, follow "Finish" in
+`update-content/SKILL.md`, with only the proofreading fixes in it.

.agents/skills/review-translation/SKILL.md

@@ -3,27 +3,35 @@ name: review-translation
 description:
   Checks translated docs pages against the English in a fresh session, fixes
   clear problems (changed meaning, literal phrasing, broken house style rules),
-  and reports the rest. Does not commit or open a PR. Use after /translate
-  pages, once the section is committed.
+  and reports the rest. Commits its fixes on their own; does not push or open a
+  PR. /translate runs it in a fresh subagent; run it yourself to review pages
+  already translated.
 disable-model-invocation: true
 ---
 
 # Review a translation
 
-Run `/review-translation <scope>` in a fresh session, not the one that
-translated the pages: a translator is poor at spotting its own mistakes. Commit
-the translation first, so the review's fixes show up as their own diff. The
-scope is the same as for `/translate pages`: one page, one folder under `docs/`,
-or one sidebar category. If no scope is given, ask.
+Run `/review-translation <scope>` in a fresh session or subagent, not the one
+that translated the pages: a translator is poor at spotting its own mistakes.
+`/translate` starts one for you when it finishes. The scope is the same as for
+`/translate pages`: one page, one folder under `docs/`, or one sidebar category.
+If no scope is given, review the translated pages this branch changes
+(`git diff --name-only origin/main...HEAD -- i18n/`), and ask only if there are
+none. The check takes the English paths, so drop the
+`i18n/<locale>/docusaurus-plugin-content-docs/current/` prefix and put `docs/`
+in its place.
+
+The translation must be committed first, so the review's fixes show as their own
+diff. If a page in scope has uncommitted changes, ask.
 
 The review checks against the rules the translator followed: "How to translate"
 in `.agents/skills/translate/SKILL.md`, the house style in
 `.agents/skills/translate/<locale>.md`, the rules for the locale in
 `translation-rules.yml`, and `glossary.yml`.
 
-The review fixes clear problems in `machine` pages and reports the rest. It does
-not commit, open a PR, or add rules. Never edit a `human-reviewed` page or a
-fenced block; report the problem instead.
+The review fixes clear problems in `machine` pages, commits them, and reports
+the rest. It does not push, open a PR, or add rules. Never edit a
+`human-reviewed` page or a fenced block; report the problem instead.
 
 ## 1. Lay out the pages
 
@@ -40,12 +48,13 @@ reading for them:
 - Run the check:
 
   ```bash
-  node .agents/skills/translate/check-translation.js <locale> docs/<path>.md...
+  node .agents/skills/translate/check-translation.js <locale> docs/<path>...
   ```
 
-  Each block it lists is a candidate, not a verdict: read it against the
-  English. It skips rules with their context in brackets, like "upgrade (a
-  plan)", so search for those by hand.
+  Each item it lists is a candidate, not a verdict: read it against the English.
+  It also checks code, links, headings, anchors, and front matter against the
+  English, so you don't need to count them. It skips rules with their context in
+  brackets, like "upgrade (a plan)", so search for those by hand.
 
 - Punctuation `<locale>.md` rules out, such as curly quotes.
 - English terms kept from `glossary.yml` written with a capital mid-sentence, if
@@ -64,8 +73,9 @@ Check that the translation:
   forms that read as "usted".
 - **Keeps names of things in the app** exactly as in the English, and keeps
   links and inline code the same.
-- **Is consistent across the scope.** The same English term gets the same
-  translation on every page.
+- **Is consistent with the rest of the locale.** The same English term gets the
+  same translation on every page. Search all of `i18n/<locale>/` for the other
+  translations of a term, not only the pages in scope.
 
 Do not flag wording you would only have written differently. If the English
 itself is wrong or unclear, note it under "Problems in the English" and leave
@@ -76,25 +86,29 @@ the translation matching it.
 Fix a block when the problem and the fix are both clear. Change only the words
 that are wrong, so the diff shows just the fix. Leave the front matter alone.
 Then run `yarn prettier --write <files>` on the pages you changed, and run the
-check again.
+check again. Commit the fixes on their own, such as "Review es translation of
+build". Do not push.
 
 ## 5. Report
 
-Build the site and serve it (`yarn serve`), so each item can point to the page
-as the reader sees it. Report in the chat. Place each item by the page URL, such
-as `http://localhost:3000/es/documentation/build/triggers`, and the section
-heading, not by file and line. Group the items like this:
+Report in the chat. Do not build or serve the site first; the report should not
+wait on it. Place each item by the page URL the check prints, such as
+`http://localhost:3000/es/documentation/build/triggers`, and the section
+heading, not by file and line. Group the items in this order:
 
+- **Needs a decision.** Problems you were not sure how to fix, or where the fix
+  changes meaning. Give the English sentence and the current translation in
+  full, and the options as full sentences, with the one you recommend first.
 - **Fixed.** For each fix, give the English sentence, the translation before,
   and the translation after, all in full, with the changed words in bold. Then
   say why in one line.
-- **Needs a decision.** Problems you were not sure how to fix, or where the fix
-  changes meaning. Quote the English and the current translation.
-- **Problems in the English.**
+- **Problems in the English.** The same format. Do not fix them; they are
+  follow-ups for a later English PR.
 - **Suggested rules.** A problem found on more than one page, or likely to come
   back in later sections, with the line you would add to `<locale>.md` or
   `translation-rules.yml`. Add it only if asked.
-- **Page to spot-check.** The page with the most fixes, with its URL.
+- **Page to spot-check.** The page with the most fixes, with its URL. To see it,
+  the user runs `yarn build` and `yarn serve`.
 
 ## Marking a page human-reviewed
 

.agents/skills/translate/SKILL.md

@@ -5,8 +5,8 @@ description:
   docusaurus.config.js, either a set of English pages or the interface text
   (navbar, footer, sidebar headings, homepage). Respects glossary.yml,
   translation-rules.yml, each locale's house style, review status, and
-  do-not-retranslate fences, and opens one PR per locale. Use when asked to
-  translate or refresh translations.
+  do-not-retranslate fences, runs a review in a fresh subagent, and opens one PR
+  per locale when asked. Use when asked to translate or refresh translations.
 disable-model-invocation: true
 ---
 
@@ -28,25 +28,58 @@ need.
   `sidebars-main.js`, the navbar or footer in `docusaurus.config.js`, or any
   `<Translate>` text in `src/` has changed. See `interface.md`.
 
-If you are not told which task, work out which ones are needed from what has
-changed in English, say so, and ask before starting.
+If you are not told which task, run `status.js` (below) with no scope. It lists
+the pages that need work and whether the interface text may have changed. Say
+what it found and ask before starting.
 
 Never translate the generated adaptor pages, or articles and blog posts.
 
 ## Before you start
 
-Check these five things. If any fails, stop and ask.
+```bash
+node .agents/skills/translate/status.js <locale> [docs/<path>...]
+```
+
+It runs the checks before translating, then lists each page in scope as missing,
+stale, up to date, or orphaned, with the diff to read, the hash to record, and
+the page's local URL. For a sidebar category, pass its files or folder. If a
+check fails, stop and ask. Do not enable a locale yourself; that changes what
+gets deployed.
+
+Translate only English that is on `main`. If the English you are asked to
+translate is on a branch that has not merged, stop and say so: its PR merges
+first.
+
+## Make the locale branch
+
+If you are on `main`, make a branch from it. If you are on another branch, such
+as a translation branch like `i18n-es`, ask whether to branch from `main` or
+from that branch. Name the branch after the scope plus the locale, such as
+`notifications-es`. Everything below is committed on it, and becomes one PR.
+
+## Fix the English first
 
-- The locale is enabled in `docusaurus.config.js`. Do not enable it yourself;
-  that changes what gets deployed.
-- `i18n/` is not in `.gitignore`.
-- `glossary.yml` and `translation-rules.yml` are valid YAML.
-- The locale has a house style guide, `<locale>.md`, in this folder.
-- Your branch has everything on `main`. Run `git fetch origin main` and then
-  `git merge-base --is-ancestor origin/main HEAD`. If it fails, the English you
-  would translate is out of date, and the hashes you record will not match
-  `main`. Ask to merge `main` in first. If your branch comes off another branch,
-  merge `main` into that one, then that one into yours.
+Settle the English before you translate it. A fix after translating makes the
+translation stale. Follow `.agents/skills/proofread/SKILL.md` on the pages
+`status.js` lists as missing or stale. Leave up-to-date pages alone; a fix there
+would make their translation stale. It fixes basic typos without asking and
+reports the rest.
+
+Only those typo fixes go in the locale PR. Anything else it reports, such as a
+wrong fact or an unclear sentence, needs its own English PR: list it under
+"Problems in the English" and translate the English as it stands. If a problem
+is bad enough that the page should not be translated until it is fixed, stop and
+ask.
+
+If the English changed, run `yarn prettier --write` on those pages and commit
+them on their own, before you translate. Do not push. The fixes change the
+English hashes, so run `status.js` again and use the hashes it prints now. Then
+translate from the fixed English, and list every fix in the report.
+
+Once the English is committed, leave it alone for the rest of the run. Problems
+found later, such as by the review, are follow-ups for the PR description. When
+the English is fixed in a later PR, the next `/translate` finds the page stale
+and updates only the changed blocks.
 
 ## How to translate
 
@@ -66,10 +99,29 @@ These apply to both tasks.
 - Keep the names of things in the app, like buttons, menus, tabs, and field
   labels, exactly as they are in the English. The app is English only, so a
   translated button name points the reader at a button that does not exist.
+- Before choosing a word for a term, search the existing translations for it, so
+  the same English gets the same translation on every page.
+
+For more than three pages, split them across subagents, two or three pages each,
+grouped by folder. First read the pages for terms that have no translation yet,
+such as a new feature name, and choose a word for each, so every subagent uses
+the same one. Give each subagent its pages, those words, the paths to this file
+and `pages.md`, and the status line for each page. Each writes its pages and
+runs the check.
+
+## Review
+
+When the pages are written and the check is clean, commit them on the locale
+branch. Do not push. Then run `/review-translation` in a new subagent, with the
+English paths of the pages you just wrote as its scope, not the scope you were
+given: read `.agents/skills/review-translation/SKILL.md` and pass it to a fresh
+agent, not a fork. A translator is poor at spotting its own mistakes, so the
+reviewer must not share your reasoning. It commits its fixes on their own, so
+the translation and the review show as separate diffs.
 
-## Before you open the PR
+## Build
 
-Build the site and make sure it passes:
+Build once the review has committed its fixes, so the build covers them.
 
 ```bash
 yarn generate-adaptors
@@ -78,14 +130,41 @@ yarn build
 
 Build the whole site, not just your locale. `yarn build --locale <locale>`
 builds the locale at the site root, so every correct `/es/...` link shows up as
-broken.
-
-Open one PR per locale, separate from the English PR. Commit each locale on its
-own branch, created from the current one and named after it plus the locale,
-such as `fix-alerts-es`. If the English is not on `main` yet, open the PR
-against the English branch and say so in the description. Translated files do
-not count toward the 20-file limit, because a locale's translations are reviewed
-as a set. In the PR description, say which tool and model translated the text. If
-you spot a problem in the English while translating, list it in the PR
-description under "Problems in the English", with the file and line. Do not fix
-it in this PR.
+broken. If `yarn generate-adaptors` hits GitHub's rate limit and
+`adaptors/packages/` already exists, build without it. If the build fails on a
+sidebar id that no longer exists, run `yarn clear` and build again.
+
+## Report
+
+Report in the chat, in this order. Place each item by its page URL and section
+heading, not by file and line.
+
+1. **Needs a decision.** Review items you need the user to decide, and OpenFn
+   feature names you translated that are not in `glossary.yml` (with the word
+   you chose). For each, give the English sentence, and the translation before
+   and after, in full.
+2. **Fixed.** Fixes made to the English, then fixes made by the review. The same
+   format, with one line on why.
+3. **Problems in the English.** What the review found in the English, left for a
+   later PR.
+4. **What changed.** For each page, how many blocks changed and how many needed
+   new text.
+5. **Page to spot-check.** The page the review fixed most, with its URL.
+6. **Status.** The build result, the branch, the commits (English, translation,
+   review), and what is uncommitted.
+
+## Push and open the PR
+
+Push and open the PR only when the user says to. Open it against the branch the
+locale branch was made from. The PR holds three commits: the English fixes, the
+translation, and the review. Say in the description that it includes English
+fixes, so an English reviewer looks at that commit.
+
+While only one locale is enabled, the English fixes go in the locale PR. Once
+there are two, put them in their own PR first, so each locale PR does not carry
+the same English commit.
+
+Translated files do not count toward the 20-file limit, because a locale's
+translations are reviewed as a set. In the PR description, say which tool and
+model translated the text, and list anything left from "Needs a decision" and
+"Problems in the English".