Config Comment Minimization Plan

Companion worklist to ADR-064 and CONFIG_COMMENT_STYLE.md.

Goal: identify the shipped baseline YAML resources whose # comment blocks should be brought into the ADR-064 two-part shape (standalone summary line + prose detail + # @... directives), ordered so that the locale translation burden stays as small as possible. Comment blocks in baseline files are mirrored into all shipped locales (cat, de, es, fr, it, ja, ko, nl, pl, pt, ru, zh), so each line edited in a baseline is a line a translator may have to re-touch. Fewer, shorter, stable first lines == trivial translation updates.

Scope and triviality model

Baseline files live under rtp-plugin/src/main/resources/ (full edition) and rtp-plugin/src/lite/resources/ (lite variant). The locale tree carries: config.yml, economy.yml, effects.yml, integrations.yml, logging.yml, messages.yml, metrics.yml, network.yml, performance.yml, regions.yml, safety.yml, worlds.yml.

A comment edit is translation-trivial when it does NOT change the meaning a translator must convey:

• Adding / reordering # @type, # @options, # @range, # @unit, # @default, # @source directive lines. Directives stay verbatim across locales (never translated), so adding them is a zero-translation change.
• Moving an existing sentence to be the standalone first line, without rewording it. The preceding comment changes shape but the locale text is reusable.
• version: sentinel and file-header doc links: never translated.

A comment edit is non-trivial (forces real translation work in 13 locales) when it rewords prose, splits one sentence into two, or adds new prose detail. Prefer trivial edits; defer prose rewrites to dedicated, per-locale passes per TRANSLATION_GUIDE.md section 8.

Priority list (do these, in this order)

Ordering favors high payoff (file is menu-surfaced and heavily commented) with low translation cost (directive-only / first-line-reorder edits).

#	File	Comment lines	State vs ADR-064	Minimal action	Translation cost
1	performance.yml	~135	Mostly conformant (summary + @ directives already present)	Verify each option's first line is a standalone summary; add missing @type/@range/@unit. No prose rewrites.	Trivial (directive-only)
2	economy.yml	~28	Conformant	Spot-check only; already two-part with directives.	None expected
3	metrics.yml	~24	Conformant; uses prose "Accepted values:" alongside @type: enum	Add @options: ["mean","max"]; leave prose.	Trivial
4	logging.yml	~18	Terse one-liners, no directives	Add # @type: boolean per toggle; first lines already standalone summaries, keep wording.	Trivial (directive-only)
5	integrations.yml	~3	One shared block above many keys	Add a short standalone summary + # @type: boolean per reroll* key; reuse the existing sentence text.	Low (one sentence, reused)
6	config.yml	~68	Mixed	Reorder so first line is a summary; add directives. Avoid rewording prose.	Mostly trivial
7	safety.yml	~110	Mixed; list-valued options	Add directives (@type: list<material>, @source: material); keep prose.	Mostly trivial
8	network.yml	~138	Heavy prose; NOT key-translated (no network.lang.yml)	Tighten first lines + add directives; comments still mirror to locales.	Low-to-medium
9	messages.yml	~302	User-facing values are the translated payload here, not comments	Do NOT bulk-touch. Only ensure section-header first lines read standalone.	High if reworded - avoid

Files intentionally excluded:

• language.yml, plugin.yml: not part of the menu/locale comment pipeline (plugin.yml is the Bukkit manifest; language.yml is the bootstrap selector).
• effects.yml, regions.yml, worlds.yml: present in the locale tree but not under resources/ root as standalone baselines here; treat opportunistically with the same rules when edited for substantive reasons.

Working procedure (per file)

1. Edit the baseline file only (src/main/resources/<file>.yml and, if it differs, src/lite/resources/<file>.yml). Apply the ADR-064 shape with directive-only / first-line-reorder edits where possible.
2. Run the locale TSV pipeline so the change reaches every locale without hand editing locale YAML:

   .\scripts\locale-files-to-csv.ps1
   .\scripts\reconcile-locale-csvs.ps1
   # translate only genuinely reworded prose in scripts\out\locale-<lang>.tsv
   .\scripts\locale-files-from-csv.ps1
   

3. Verify:

   .\gradlew :rtp-plugin:test --tests "*LocaleParityTest*"
   .\gradlew build
   

Stay-on-task note

This is a transition worklist, not a mandate to bulk-reformat in one change. Per the Stay-On-Task Policy and CONFIG_COMMENT_STYLE.md "When updating existing files", reformat a file only when already editing it or as a dedicated, isolated change. Delete this note once the priority list is exhausted.