Add copydeck notes and export/import scripts

Author: grega

.gitignore

@@ -1,3 +1,6 @@
+# Ignore any exported CSV files (see scripts/)
+copydeck*.csv
+
 # Node / TypeScript
 node_modules/
 dist/

README.md

@@ -65,6 +65,16 @@ npm run build -- --watch
 npm test
 ```
 
+### Copydecks
+
+Copydecks are JSON files that contain rules and templates for matching and explaining errors. They are stored in `copydecks/` and can be edited or added to.
+
+New error explanations can (should) be generated by an LLM, for ease (TODO: add system instructions for this). The generated content *must* be reviewed and edited by an appropriately-qualified human (eg. learning managers) prior to release, to ensure accuracy and clarity.
+
+Copydecks contain prompts and additional context for localisation.
+
+For management of human-reviewed copydeck content, scripts (in `./scripts`) are provided to extract and update copydeck content in a Google Sheet (and re-import it after review).
+
 ## Building
 
 Create a clean build for distribution:

scripts/export_copydeck_csv.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+"""Export copydeck error messages to CSV for Google Sheets review.
+
+Usage:
+    python scripts/export_copydeck_csv.py
+    python scripts/export_copydeck_csv.py --copydeck copydecks/fr/copydeck.json --out review_fr.csv
+"""
+
+import argparse
+import csv
+import json
+import sys
+from pathlib import Path
+
+COLUMNS = ["error_type", "variant_index", "if_condition", "title", "summary", "why",
+           "step_1", "step_2", "step_3", "step_4", "step_5"]
+
+
+def export(copydeck_path: Path, out_path: Path) -> None:
+    with open(copydeck_path) as f:
+        data = json.load(f)
+
+    rows = []
+    for error_type, error_def in data["errors"].items():
+        for i, variant in enumerate(error_def["variants"]):
+            steps = variant.get("steps", [])
+            if_condition = variant.get("if")
+            row = {
+                "error_type": error_type,
+                "variant_index": i,
+                "if_condition": json.dumps(if_condition) if if_condition else "",
+                "title": variant.get("title", ""),
+                "summary": variant.get("summary", ""),
+                "why": variant.get("why", ""),
+            }
+            for j in range(1, 6):
+                row[f"step_{j}"] = steps[j - 1] if j - 1 < len(steps) else ""
+            rows.append(row)
+
+    with open(out_path, "w", newline="", encoding="utf-8") as f:
+        writer = csv.DictWriter(f, fieldnames=COLUMNS)
+        writer.writeheader()
+        writer.writerows(rows)
+
+    print(f"Exported {len(rows)} variants to {out_path}")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Export copydeck to CSV for review")
+    parser.add_argument("--copydeck", default="copydecks/en/copydeck.json",
+                        help="Path to source copydeck JSON (default: copydecks/en/copydeck.json)")
+    parser.add_argument("--out", default="copydeck_review.csv",
+                        help="Output CSV path (default: copydeck_review.csv)")
+    args = parser.parse_args()
+
+    copydeck_path = Path(args.copydeck)
+    if not copydeck_path.exists():
+        print(f"Error: {copydeck_path} not found", file=sys.stderr)
+        sys.exit(1)
+
+    export(copydeck_path, Path(args.out))
+
+
+if __name__ == "__main__":
+    main()

scripts/import_copydeck_csv.py

@@ -0,0 +1,80 @@
+#!/usr/bin/env python3
+"""Import revised copy from CSV back into a copydeck JSON.
+
+Reads the reviewed CSV (produced by export_copydeck_csv.py), updates title/summary/why/steps
+for each variant, and writes the result to a new JSON file. The original if_condition and
+_placeholders metadata are preserved from the source copydeck.
+
+Usage:
+    python scripts/import_copydeck_csv.py
+    python scripts/import_copydeck_csv.py --csv copydeck_review.csv --copydeck copydecks/en/copydeck.json --out copydecks/en/copydeck_revised.json
+"""
+
+import argparse
+import csv
+import json
+import sys
+from pathlib import Path
+
+
+def import_csv(csv_path: Path, copydeck_path: Path, out_path: Path) -> None:
+    with open(copydeck_path) as f:
+        data = json.load(f)
+
+    with open(csv_path, newline="", encoding="utf-8") as f:
+        rows = list(csv.DictReader(f))
+
+    updated = 0
+    for row in rows:
+        error_type = row["error_type"]
+        variant_index = int(row["variant_index"])
+
+        if error_type not in data["errors"]:
+            print(f"Warning: error type '{error_type}' not found in copydeck, skipping", file=sys.stderr)
+            continue
+
+        variants = data["errors"][error_type]["variants"]
+        if variant_index >= len(variants):
+            print(f"Warning: variant index {variant_index} out of range for {error_type}, skipping", file=sys.stderr)
+            continue
+
+        variant = variants[variant_index]
+        variant["title"] = row["title"]
+        variant["summary"] = row["summary"]
+        variant["why"] = row["why"]
+
+        steps = [row[f"step_{j}"] for j in range(1, 6) if row.get(f"step_{j}", "").strip()]
+        if steps:
+            variant["steps"] = steps
+        elif "steps" in variant:
+            del variant["steps"]
+
+        updated += 1
+
+    with open(out_path, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2, ensure_ascii=False)
+        f.write("\n")
+
+    print(f"Updated {updated} variants → {out_path}")
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Import reviewed CSV back into copydeck JSON")
+    parser.add_argument("--csv", default="copydeck_review.csv",
+                        help="Input CSV path (default: copydeck_review.csv)")
+    parser.add_argument("--copydeck", default="copydecks/en/copydeck.json",
+                        help="Source copydeck JSON to update (default: copydecks/en/copydeck.json)")
+    parser.add_argument("--out", default="copydecks/en/copydeck.json",
+                        help="Output JSON path (default: overwrites source copydeck)")
+    args = parser.parse_args()
+
+    for p in [Path(args.csv), Path(args.copydeck)]:
+        if not p.exists():
+            print(f"Error: {p} not found", file=sys.stderr)
+            sys.exit(1)
+
+    import_csv(Path(args.csv), Path(args.copydeck), Path(args.out))
+
+
+if __name__ == "__main__":
+    main()