reportist/docs/report-contract.md

56 lines
2.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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](../visual/README.md);
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:
```yaml
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`),
custom metadata labels, and status/severity values remain as supplied.
Add any number of languages to
[`plugins/report/locales.json`](../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`:
```json
"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.