paperlint 14.4.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.4.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:ed201d81c5934675 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
 
@@ -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

@@ -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/closed-choice-generator.md

@@ -229,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.
 
@@ -286,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-browser.test.ts

@@ -1418,3 +1418,220 @@ test(
   },
   BROWSER_TEST_MS,
 );
+
+// ── a second language for the page's own words (#394) ──────────────────────────────────────────
+const RU_FIXTURE = join(import.meta.dirname, "fixtures", "v7-cards-ru.json");
+const Words = z.object({
+  labels: z.object({ for_example: z.string() }).loose(),
+  questions: z.array(
+    z.object({
+      id: z.string(),
+      text: z.string(),
+      options: z.array(
+        z.object({
+          value: z.string(),
+          label: z.string(),
+          example: z.string(),
+          icon: z.string(),
+        }),
+      ),
+    }),
+  ),
+});
+const RU_RAW = z.json().parse(JSON.parse(readFileSync(RU_FIXTURE, "utf8")));
+const RU_WORDS = z
+  .object({
+    situation_question: z.string(),
+    labels: z.object({ for_example: z.string() }).loose(),
+    questions: z.record(
+      z.string(),
+      z.object({
+        text: z.string(),
+        options: z.record(
+          z.string(),
+          z.object({ label: z.string(), example: z.string() }),
+        ),
+      }),
+    ),
+  })
+  .parse(RU_RAW);
+/** The fixture's page words in one language: the base's, or the Russian translation laid over them. */
+function wordsIn(lang: "en" | "ru") {
+  const base = Words.parse({
+    labels: { for_example: "For example: " },
+    questions: z.object({ questions: z.unknown() }).loose().parse(V7_CONFIG)
+      .questions,
+  });
+  if (lang === "en") return base;
+  return {
+    labels: RU_WORDS.labels,
+    questions: base.questions.map((q) => ({
+      ...q,
+      text: RU_WORDS.questions[q.id]?.text ?? "",
+      options: q.options.map((o) => ({
+        ...o,
+        ...RU_WORDS.questions[q.id]?.options[o.value],
+      })),
+    })),
+  };
+}
+/** What the docstring card and the how-to rows say in `lang`, as the fixture states it. */
+function expectedIn(lang: "en" | "ru") {
+  const card = fixtureCard("card-docstring");
+  const { situation, quote } = z
+    .object({
+      situation: z.object({ question: z.string() }),
+      quote: z.object({ text: z.string() }),
+    })
+    .loose()
+    .parse(card);
+  const w = wordsIn(lang);
+  const [q] = w.questions;
+  assert.ok(q !== undefined);
+  const notes = card.answer_notes.forbid;
+  return {
+    switch: { lang, langs: ["en", "ru"] },
+    quote: unticked(quote.text),
+    question:
+      lang === "en"
+        ? situation.question
+        : RU_WORDS.situation_question.replace(
+            "{n}",
+            String(card.excerpt.lines.find((l) => l.mark)?.n),
+          ),
+    answers: q.options.map((o) => [
+      { question: q.id, value: o.value },
+      `${o.icon}${o.label}${unticked(notes[o.value] ?? "")}`,
+    ]),
+    howTo: [
+      q.text,
+      ...q.options.map(
+        (o) => `${o.icon} ${o.label}${w.labels.for_example}${o.example}`,
+      ),
+    ],
+  };
+}
+/** The same, read from the page. */
+async function shownIn(page: Page, card: Locator) {
+  const texts = async (scope: Page | Locator, kind: string) =>
+    scope.getByTestId(kind).allTextContents();
+  return {
+    switch: await metaOf(page.getByTestId("lang-switch")),
+    quote: (await texts(card, "quote")).join(""),
+    question: (await texts(card, "question")).join(""),
+    answers: await Promise.all(
+      (await allByKind(card, "answer")).map(async (a) => [
+        a.meta,
+        await a.loc.textContent(),
+      ]),
+    ),
+    howTo: [
+      ...(await texts(page, "how-to-question")),
+      ...(await texts(page, "how-to-answer")),
+    ],
+  };
+}
+test(
+  "🔴 the language switch swaps the page's own words both ways, keeps the quote and the code as built, and is remembered over a reload",
+  async () => {
+    const cfg = {
+      ...R.omit(V7_CONFIG, ["min_seconds"]),
+      translations: { ru: RU_RAW },
+    };
+    const { page: html, key } = build(setup("browser-v7-lang", cfg));
+    const at = "http://label.test/";
+    const page = await (
+      await sharedBrowser()
+    ).newPage({ viewport: { width: 400, height: 800 } });
+    try {
+      // A real origin, so the page has a localStorage; every other request is refused, none leaves.
+      await page.route("**/*", (r) =>
+        r.request().url() === at
+          ? r.fulfill({ contentType: "text/html; charset=utf-8", body: html })
+          : r.abort(),
+      );
+      await page.addInitScript(
+        STORE(
+          Object.fromEntries(
+            ["forbid", "allow", "elsewhere"].map((v, n) => [
+              `r1-P${String(n + 1)}`,
+              { answers: { forbid: v }, source: "page" },
+            ]),
+          ),
+          20,
+        ),
+      );
+      await page.goto(at, { waitUntil: "domcontentloaded" });
+      const id = Object.entries(key.ids).find(
+        ([, v]) => v.source_id === "card-docstring",
+      )?.[0];
+      const card = async () => {
+        await page.getByTestId("item").first().waitFor();
+        const found = (await allByKind(page, "item")).find(
+          (c) => Id.parse(c.meta).id === id,
+        );
+        assert.ok(found !== undefined, "the card is drawn");
+        return found.loc;
+      };
+      const option = async (lang: string) =>
+        (await allByKind(page, "lang-option")).find(
+          (o) => z.object({ lang: z.string() }).parse(o.meta).lang === lang,
+        )?.loc;
+      assert.deepEqual(await shownIn(page, await card()), expectedIn("en"));
+      await (await option("ru"))?.click();
+      assert.deepEqual(await shownIn(page, await card()), expectedIn("ru"));
+      await page.reload({ waitUntil: "domcontentloaded" });
+      assert.deepEqual(await shownIn(page, await card()), expectedIn("ru"));
+      await (await option("en"))?.click();
+      assert.deepEqual(await shownIn(page, await card()), expectedIn("en"));
+    } finally {
+      await page.context().close();
+    }
+  },
+  BROWSER_TEST_MS,
+);
+
+test(
+  "🔴 a page without translations names its own language on the document: the one it declares, else English",
+  async () => {
+    const htmlLang = async (cfg: Record<string, unknown>, dir: string) => {
+      const { page: html } = build(setup(dir, cfg));
+      const at = "http://label.test/";
+      const page = await (
+        await sharedBrowser()
+      ).newPage({ viewport: { width: 400, height: 800 } });
+      try {
+        await page.route("**/*", (r) =>
+          r.request().url() === at
+            ? r.fulfill({ contentType: "text/html; charset=utf-8", body: html })
+            : r.abort(),
+        );
+        await page.addInitScript(
+          STORE(
+            Object.fromEntries(
+              ["forbid", "allow", "elsewhere"].map((v, n) => [
+                `r1-P${String(n + 1)}`,
+                { answers: { forbid: v }, source: "page" },
+              ]),
+            ),
+            20,
+          ),
+        );
+        await page.goto(at, { waitUntil: "domcontentloaded" });
+        await page.getByTestId("item").first().waitFor();
+        return await page.evaluate(() => document.documentElement.lang);
+      } finally {
+        await page.context().close();
+      }
+    };
+    const plain = R.omit(V7_CONFIG, ["min_seconds"]);
+    assert.deepEqual(
+      [
+        await htmlLang(plain, "browser-v7-lang-none"),
+        await htmlLang({ ...plain, lang: "de" }, "browser-v7-lang-de"),
+      ],
+      ["en", "de"],
+    );
+  },
+  BROWSER_TEST_MS,
+);