paperlint 14.3.0 → 14.5.0

package/dist/skills/build-label-page/scripts/label-page-core.d.ts

@@ -193,8 +193,45 @@ interface Config {
     readonly practice: readonly Practice[];
     readonly practice_round?: number;
     readonly labels?: Readonly<Record<string, string>>;
+    readonly lang?: string;
+    readonly translations?: Readonly<Record<string, Translation>>;
     readonly items: readonly Item[];
 }
+interface QuestionWords {
+    readonly text: string;
+    readonly short?: string;
+    readonly options: Readonly<Record<string, {
+        readonly label: string;
+        readonly example: string;
+        readonly ask_why?: string;
+    }>>;
+}
+/** The page's own words in one more language (#394). */
+interface Translation {
+    readonly title?: string;
+    readonly intro?: string;
+    readonly labels?: Readonly<Record<string, string>>;
+    readonly situation_question?: string;
+    readonly questions: Readonly<Record<string, QuestionWords>>;
+}
+/**
+ * Every language of the page with its words whole, the translations checked: each covers every
+ * question and answer of the page and names none it does not have, and gives an intro, a reason
+ * prompt and a situation question exactly where the page shows one. A label it leaves out reads as
+ * in the page's own language.
+ */
+declare function translationsOf(cfg: Config): {
+    [x: string]: {
+        questions: Question[];
+        situation_question?: string;
+        title: string;
+        intro: string;
+        labels: {
+            [x: string]: string;
+        };
+    };
+};
+type Translated = ReturnType<typeof translationsOf>;
 interface KeyEntry {
     readonly source_id: string;
     readonly group: string;
@@ -212,7 +249,7 @@ declare function itemsOnPage(cfg: Config, keyPath: string): {
     idOf: (i: Item) => string;
 };
 /** What a page shows: the questions, the practice and the items, blind, with their neutral ids. */
-declare function payloadOf(cfg: Config, page: ReturnType<typeof itemsOnPage>, described: Described): {
+declare function payloadOf(cfg: Config, page: ReturnType<typeof itemsOnPage>, described: Described, translated: Translated): {
     questions: readonly Question[];
     practice: {
         round: number;
@@ -247,6 +284,71 @@ declare function payloadOf(cfg: Config, page: ReturnType<typeof itemsOnPage>, de
         }[];
         id: string;
     })[];
+    lang?: string;
+    answerers?: readonly string[];
+    min_seconds?: number;
+    title: string;
+    intro: string;
+    labels: {
+        [x: string]: string;
+    };
+    groups: {
+        id: string;
+        label: string;
+    }[];
+    familiarity_question: string;
+    familiarity: {
+        value: string;
+        label: string;
+    }[];
+    allowed: JsonObject;
+} | {
+    questions: readonly Question[];
+    practice: {
+        round: number;
+        items: ({
+            rules?: never;
+            id: string;
+            expected: Readonly<Record<string, string>>;
+            why: string;
+        } | {
+            rules: {
+                description?: string;
+                family?: string;
+                linter: "eslint" | "ruff";
+                id: string;
+            }[];
+            id: string;
+            expected: Readonly<Record<string, string>>;
+            why: string;
+        })[];
+    };
+    items: ({
+        answerers?: readonly string[];
+        rules?: never;
+        id: string;
+    } | {
+        answerers?: readonly string[];
+        rules: {
+            description?: string;
+            family?: string;
+            linter: "eslint" | "ruff";
+            id: string;
+        }[];
+        id: string;
+    })[];
+    lang: string;
+    translations: {
+        [x: string]: {
+            questions: Question[];
+            situation_question?: string;
+            title: string;
+            intro: string;
+            labels: {
+                [x: string]: string;
+            };
+        };
+    };
     answerers?: readonly string[];
     min_seconds?: number;
     title: string;
@@ -307,6 +409,71 @@ export declare function prepareBuild(configPath: string, outDir: string): {
             }[];
             id: string;
         })[];
+        lang?: string;
+        answerers?: readonly string[];
+        min_seconds?: number;
+        title: string;
+        intro: string;
+        labels: {
+            [x: string]: string;
+        };
+        groups: {
+            id: string;
+            label: string;
+        }[];
+        familiarity_question: string;
+        familiarity: {
+            value: string;
+            label: string;
+        }[];
+        allowed: JsonObject;
+    } | {
+        questions: readonly Question[];
+        practice: {
+            round: number;
+            items: ({
+                rules?: never;
+                id: string;
+                expected: Readonly<Record<string, string>>;
+                why: string;
+            } | {
+                rules: {
+                    description?: string;
+                    family?: string;
+                    linter: "eslint" | "ruff";
+                    id: string;
+                }[];
+                id: string;
+                expected: Readonly<Record<string, string>>;
+                why: string;
+            })[];
+        };
+        items: ({
+            answerers?: readonly string[];
+            rules?: never;
+            id: string;
+        } | {
+            answerers?: readonly string[];
+            rules: {
+                description?: string;
+                family?: string;
+                linter: "eslint" | "ruff";
+                id: string;
+            }[];
+            id: string;
+        })[];
+        lang: string;
+        translations: {
+            [x: string]: {
+                questions: Question[];
+                situation_question?: string;
+                title: string;
+                intro: string;
+                labels: {
+                    [x: string]: string;
+                };
+            };
+        };
         answerers?: readonly string[];
         min_seconds?: number;
         title: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "paperlint",
-  "version": "14.3.0",
+  "version": "14.5.0",
   "description": "A linter for scientific papers written in LaTeX: catches mistakes before you submit to a conference or journal.",
   "type": "module",
   "license": "MIT",

package/skills/build-label-page/SKILL.md

@@ -4,7 +4,7 @@ description: Build a phone labelling page published as a claude.ai Artifact with
 allowed-tools: [Read, Write, Edit, Grep, Glob, Bash, Artifact, ArtifactData]
 ---
 
-<!-- vigiles:sha256:9d7a2c35df4e6a10 compiled from skills/build-label-page/SKILL.md.spec.ts -->
+<!-- vigiles:sha256:46ebfc043d459ff0 compiled from skills/build-label-page/SKILL.md.spec.ts -->
 
 # build-label-page — a page the person labels on a phone, and the labels back in the repo
 
@@ -57,7 +57,7 @@ building. In one line each:
    passing proves nothing about this.
 2. **Navigation never relies on in-page scrolling or toasts.** "Next unanswered" is a filter: it hides
    every finished item and group, and a note at the top lists what is left and what each still needs.
-3. **An item is done only when every question on it is answered.** The card names the missing
+3. **An item is done only when every question on it is answered.** The card asks the missing
    question; the progress counter counts complete items only.
 4. **Blind.** Neutral ids (`G001`…), order shuffled with a fixed seed, no model answers, verdicts or
    source labels on the page. The generator refuses to build when an item carries a field outside an
@@ -158,6 +158,16 @@ Two optional top-level keys of `items.json`, both left out by default:
 Details and the export's shape: [`references/closed-choice-generator.md`](references/closed-choice-generator.md),
 "Two answerers, and a minimum time on screen".
 
+## A second language
+
+A labeller who reads another language better gets the page's own words in it: `"translations": {"ru":
+{…}}` (and `"lang"`, the page's own, `en` by default) adds a switch under the title. The questions,
+answers, examples, reason prompts, intro and labels change; the quote, the code and every note never
+do, because those words are what is judged. The build refuses a translation that leaves out or
+invents a question or an answer; the ids and `key.json` are the same with or without it.
+[`references/closed-choice-generator.md`](references/closed-choice-generator.md), "A second
+language for the page's own words".
+
 ## When the page misbehaves
 
 Look at what the store holds (`ArtifactData` `list`) before changing anything: the page may be fine

package/skills/build-label-page/SKILL.md.spec.ts

@@ -68,7 +68,7 @@ building. In one line each:
    passing proves nothing about this.
 2. **Navigation never relies on in-page scrolling or toasts.** "Next unanswered" is a filter: it hides
    every finished item and group, and a note at the top lists what is left and what each still needs.
-3. **An item is done only when every question on it is answered.** The card names the missing
+3. **An item is done only when every question on it is answered.** The card asks the missing
    question; the progress counter counts complete items only.
 4. **Blind.** Neutral ids (\`G001\`…), order shuffled with a fixed seed, no model answers, verdicts or
    source labels on the page. The generator refuses to build when an item carries a field outside an
@@ -169,6 +169,16 @@ Two optional top-level keys of \`items.json\`, both left out by default:
 Details and the export's shape: [\`references/closed-choice-generator.md\`](references/closed-choice-generator.md),
 "Two answerers, and a minimum time on screen".
 
+## A second language
+
+A labeller who reads another language better gets the page's own words in it: \`"translations": {"ru":
+{…}}\` (and \`"lang"\`, the page's own, \`en\` by default) adds a switch under the title. The questions,
+answers, examples, reason prompts, intro and labels change; the quote, the code and every note never
+do, because those words are what is judged. The build refuses a translation that leaves out or
+invents a question or an answer; the ids and \`key.json\` are the same with or without it.
+[\`references/closed-choice-generator.md\`](references/closed-choice-generator.md), "A second
+language for the page's own words".
+
 ## When the page misbehaves
 
 Look at what the store holds (\`ArtifactData\` \`list\`) before changing anything: the page may be fine

package/skills/build-label-page/references/checklist.md

@@ -41,8 +41,8 @@ filter works in any frame, because the next thing to answer is simply the first
 
 ## 3. An item counts as done only when every question on it is answered
 
-**Do.** Done means all questions answered. The card shows which one is missing ("Still needs:
-boundary"). The progress counter counts complete items only, so "7 of 12" means 7 items with every
+**Do.** Done means all questions answered. The card asks the one still missing in its question
+box, and "Next unanswered" lists what each item still needs. The progress counter counts complete items only, so "7 of 12" means 7 items with every
 question answered. A group is finished when all its items are and its familiarity question (rule 5)
 is answered.
 
@@ -50,7 +50,7 @@ is answered.
 and surfaces weeks later as a gap in the data. A counter that counts partial items reports progress
 that the analysis cannot use.
 
-**Check.** Answer one question of a two-question item: the counter stays put and the card names the
+**Check.** Answer one question of a two-question item: the counter stays put and the card asks the
 other question.
 
 ## 4. Blind: the page tells the labeller nothing about the answer or the source

package/skills/build-label-page/references/closed-choice-generator.md

@@ -155,18 +155,22 @@ Any card may carry these blocks, on any `kind`, and each one is optional. The pa
 }
 ```
 
-- **Order on the card.** The card shows, in this order:
-  1. its place (`labels.place`);
-  2. the body, on a `labels.body` row when that label is set;
-  3. the repeat sentence;
-  4. the older fields (`code`, `unit`, `rules`, `readings`, `file`, `context`);
-  5. the situation's summary;
-  6. the excerpt;
-  7. **the question box**: the `quote` and its source, the question, and its answers with their `answer_notes`;
-  8. `references`, `more` and `table`, each in place under its heading. Nothing on a card is folded:
-     a labeller who has to open a block to answer reads half a card (#392).
-
-  The question therefore sits right under the code it names.
+- **Order on the card.** Each card is a bordered panel, with wide space before the next. It shows, in this order:
+  1. its place (`labels.place`), then its `title`;
+  2. the `quote` and its source;
+  3. the body, on a `labels.body` row when that label is set;
+  4. the repeat sentence;
+  5. the older fields (`code`, `unit`, `rules`, `readings`, `file`, `context`);
+  6. the situation's summary;
+  7. the excerpt;
+  8. **the question box**: the question, its answers with their `answer_notes`, and the wait bar of `min_seconds`;
+  9. the reason box of an answer with `ask_why`, then the status line. The status line never lists
+     what is missing (the question box asks it): it shows «Saved <time>», «Saving…», why a save did not happen, or nothing;
+  10. `references`, `more` and `table`, each in place under its heading. Nothing on a card is folded:
+      a labeller who has to open a block to answer reads half a card (#392).
+
+  A card is read once, top to bottom: the words asked about, the code they are about, the question
+  right under that code, its answers. A card without a `quote` has the same order without step 2.
 
 - **`situation`**: `{summary?, question}`.
   - `summary` is one sentence above the excerpt; optional.
@@ -202,7 +206,7 @@ Any card may carry these blocks, on any `kind`, and each one is optional. The pa
 }
 ```
 
-- **`quote`** shows the words being asked about at the top of the question box, `source` as a small line under them. A card needs `body` or `quote`.
+- **`quote`** shows the words being asked about at the top of the card, above its code, `source` as a small line under them. A card needs `body` or `quote`.
 - **`terms`**: each `term` must occur in the quote, its source or the annotation, inside one backtick span or outside all of them; the build refuses one it cannot find there, and a note entry with neither `quote` nor `code`. A term opens from its first occurrence in the quote, else the source, else the annotation. On the page it is a dotted button: a tap (or hover, where there is hover) opens one floating note anchored to it, at most 280 px wide (300 with a snippet), flipped above the term when there is no room below, kept inside the viewport. A tap outside closes it and does nothing else, so it never answers a card; so does Esc. Answer buttons carry no terms.
 - **`answer_notes`** puts a sub-line under an answer's label on this card: what the answer means here. A question or an answer the page does not have is refused.
 - Whether a note pushes the labeller toward one answer is not checked: the consumer lists each note for the study's author.
@@ -225,6 +229,8 @@ Any card may carry these blocks, on any `kind`, and each one is optional. The pa
   | `hidden`           | a `⋮` row for lines left out                                    | `lines {from}–{to}`            |
   | `hidden_one`       | a `⋮` row for one line left out                                 | `line {from}`                  |
   | `wait`             | the bar under the answers while `min_seconds` runs              | `⏳ You can answer in {s} s`   |
+  | `how_to`           | the heading of the first screen's questions and examples        | `📖 How to answer`             |
+  | `for_example`      | text before each example on the first screen                    | `For example: `                |
 
 - The leak guard reads every string these blocks render, one string at a time.
 
@@ -282,6 +288,60 @@ author cannot read it is an exclusion made after the draw and goes unrecorded. T
 units whose fate is obvious. Each dropped unit carries its reason in the labels file. The author's words, with the date, then go into
 `author_check` of the plan; a dropped unit is replaced by the next one in the draw.
 
+## A second language for the page's own words
+
+For a labeller who reads another language better (#394). Both keys are optional and top-level; left
+out, the page is exactly as above.
+
+```jsonc
+{
+  "lang": "en", // the language of the page's own words; "en" when left out
+  "translations": {
+    "ru": {
+      "title": "…", // optional: the page's title when left out
+      "intro": "…", // given exactly when the page has an `intro`
+      "labels": {
+        "place": "Карточка {n} из {total}",
+        "how_to": "📖 Как отвечать",
+        "for_example": "Например: ",
+      },
+      "situation_question": "Эти слова запрещают строку {n}?", // given exactly when a card has a `situation`
+      "questions": {
+        "forbid": {
+          "text": "…",
+          "short": "…", // optional: the translated `text` stands in for it
+          "options": {
+            "forbid": { "label": "Запрещают", "example": "…" },
+            "cannot": { "label": "…", "example": "…", "ask_why": "…" },
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+- **What changes with the language:** the title, the intro, the `labels`, every question's text and
+  short form, every answer's label and example, every reason prompt (`ask_why`), and the first question
+  as the cards with a `situation` ask it. The first screen's rows ("How to answer") change too.
+- **What never does:** the quote and its source, the code, the annotation, the term notes, the
+  answer sub-lines (`answer_notes`), a situation's `summary`, and every other card field. Those words
+  are what the labeller judges; a translated quote would be a different item.
+- **`situation_question`** replaces each card's own `situation.question` in that language. `{n}` is
+  the number of the card's first marked line; `{line}` works as in `situation`. Either one on a card
+  without an `excerpt` is refused by path.
+- **Refused, by path:** a translation into the page's own `lang`; a question or an answer it leaves
+  out, or one the page does not have; two answers whose labels read the same; an `intro`, an
+  `ask_why` or a `situation_question` given where the page has none, or missing where it has one.
+- **Left out on purpose:** a label the translation does not give reads as in the page's language.
+  The page's fixed words ("Practice", "Change", "Saved", "Next unanswered", "Who is answering?")
+  and the word «line» that `{line}` writes stay in English.
+- **The switch** sits under the title (`data-test="lang-switch"`), one button per language with its
+  tag ("EN", "RU"). The choice is kept in the browser's localStorage under `label-lang` when it has
+  one.
+- **Ids and key:** the neutral ids, the store's documents, `key.json` and the export are the same,
+  byte for byte, with or without translations.
+
 ## Two answerers, and a minimum time on screen
 
 Both keys are optional and top-level. Left out, the page, its store documents and the export are

package/skills/build-label-page/scripts/fixtures/v7-cards-ru.json

@@ -0,0 +1,23 @@
+{
+  "title": "Запрещают ли слова",
+  "labels": {
+    "place": "Карточка {n} из {total}",
+    "wait": "Сохранить · можно через {s} с на этой карточке",
+    "how_to": "📖 Как отвечать",
+    "for_example": "Например: "
+  },
+  "situation_question": "Эти слова запрещают строку {n}?",
+  "questions": {
+    "forbid": {
+      "text": "Эти слова запрещают отмеченную строку?",
+      "short": "запрещают ли слова?",
+      "options": {
+        "forbid": { "label": "Запрещают", "example": "«No print calls» и строка print(x)" },
+        "allow": { "label": "Разрешают", "example": "«No print calls» и строка log.info(x)" },
+        "unsettled": { "label": "Из слов это не следует", "example": "«Keep functions short» и функция на 30 строк" },
+        "elsewhere": { "label": "Слова про другое", "example": "«Use tabs» и строка с запросом к базе" },
+        "cannot": { "label": "Не берусь оценить (объясните)", "example": "строка на языке, который вы не читаете", "ask_why": "Что мешает?" }
+      }
+    }
+  }
+}

package/skills/build-label-page/scripts/label-page-blocks.test.ts

@@ -505,12 +505,12 @@ const unticked = (text: string): string => text.split("`").join("");
 const shownBy = (n: FakeNode): string => n.textContent.replace(/\n/g, "");
 /** The kinds of the card's parts, in the order they appear. */
 const KINDS = [
+  "quote",
+  "quote-source",
   "excerpt-path",
   "code-line",
   "gap",
   "annotation",
-  "quote",
-  "quote-source",
   "question",
   "answer",
   "answer-sub",
@@ -567,19 +567,18 @@ function fixtureFacts() {
       { question: V7_QUESTION.id, value: o.value },
       unticked(notes[o.value] ?? ""),
     ]),
-    status: [
-      [{ state: "missing", missing: [V7_QUESTION.id] }],
-      [`Still needs: ${V7_QUESTION.short}`],
-    ],
+    // The save button and the open question already say what is missing: the line keeps its values
+    // and shows nothing.
+    status: [[{ state: "missing", missing: [V7_QUESTION.id] }], [""]],
     order: [
+      "quote",
+      "quote-source",
       "excerpt-path",
       ...lines.flatMap((l, n) => [
         ...(l.n > (lines[n - 1]?.n ?? l.n) + 1 ? ["gap"] : []),
         "code-line",
         ...(l.mark ? ["annotation"] : []),
       ]),
-      "quote",
-      "quote-source",
       "question",
       ...V7_QUESTION.options.flatMap((o) =>
         o.value in notes ? ["answer", "answer-sub"] : ["answer"],
@@ -589,7 +588,7 @@ function fixtureFacts() {
   };
 }
 
-test("🔴 an approved card reads top to bottom: its path, the code with a gap row for what it leaves out, the marked line and the note under it, the quote, its source, the question, each answer with its sub-line, then what it still needs", async () => {
+test("🔴 an approved card reads top to bottom: the quote and its source, its path, the code with a gap row for what it leaves out, the marked line and the note under it, the question, each answer with its sub-line, then a status line that shows nothing while the card is unanswered", async () => {
   const { page: html, key } = build(setup("v7-face", v7()));
   const { app } = await openLive(html, { practice: V7_DONE });
   const id = Object.entries(key.ids).find(