reportist/docs/report-contract.md

2.4 KiB
Raw Permalink Blame History

Authored report input

The report plugin accepts YAML or JSON dictionaries. metadata.Date and metadata.Author are required. The document model supports report-specific fields such as diagnostics as well as ordinary sections, findings, actions, and appendices. Named themes are listed in the palette guide; a custom theme dictionary can also be provided. The renderer is plugins/report/.

The diagnostic plugin has a separate raw WinDiagnostics input and its own Typst document model. Both plugins import reporter/visual/elements.typ for graphical primitives.

Localisation

Set the top-level language field to select the language of built-in report headings and labels. English (en) is the default; French (fr) is included. The field works in both YAML and JSON:

language: fr
metadata:
  Author: "Marie Dupont"
  Date: "2026-09-25"
title: "Rapport d’intervention"
summary: "Le service est de nouveau disponible."

This translates section headings, timeline column headings, diagnostic labels, report-type labels, default titles, footer labels, and known metadata labels. It also sets Typst's text language. Keep metadata keys such as Author and Date unchanged. Authored text, explicit titles (including actions_title), and custom metadata labels remain as supplied. Known status and severity badge labels are translated through the same catalog; unknown values remain as supplied. Keep the source status/severity values unchanged so badge colors retain their meaning.

Add any number of languages to plugins/report/locales.json, without changing renderer code. Each top-level language code maps English labels to their translations. For example, add this entry alongside en and fr:

"es": {
  "Executive summary": "Resumen ejecutivo",
  "Findings": "Hallazgos",
  "Current state": "Estado actual"
}

Use a Typst-compatible language code and set language: es in the report. Copy the complete en entry to translate every label, or start with a partial entry: missing translations fall back to English. Values must be strings. Unknown language codes fail validation with the available languages listed. Language codes in reports are case-insensitive; catalog codes use lowercase.

Localisation applies to the authored report plugin, including its diagnostic hypotheses section. The separate raw diagnostic and consumables plugins have their own document models.