extraction agent stripped html comments with translator notes and the build failed

Fix the extraction agent stripping translator notes and failing the build

TL;DR

The agent strips HTML comments that hold translator notes, so configure it to preserve comments in message files. Those comments are the context translators rely on, and some builds validate their presence. Turn on comment preservation in the extractor config, then re-extract.

The error

Build failed: translator notes missing for 40 strings
extraction agent removed HTML comments holding the notes

Fix it

Step 1: Confirm the notes are gone from the catalog

grep -c "note" locale/en.json

Expected: The count is 0 or far below the source.

Step 2: Check the extractor comment settings

grep -n "comment\|note" scripts/extract-config.js | head -5

Expected: You see whether comment extraction is on.

Step 3: Enable comment preservation

node -e "console.log('turn on the extractor option that keeps leading comments as translator notes')"

Expected: The config now preserves comments.

Step 4: Re-extract and verify the notes return

node scripts/extract-strings.js | tail -2 && grep -c "note" locale/en.json

Expected: The note count matches the source.

When to use this

• Extraction strips HTML comments with translator notes
• A build validates note presence and fails

When NOT to use this

• The notes were never in the source, add them first
• Notes extract but the TMS ignores them, check the export

Tool and version compatibility

• Extractors with comment-to-note mapping
• Builds that validate translator context

Variant phrasings

only some notes stripped

The extractor keeps comments in some positions only. Move notes directly above the string.

notes stripped by a formatter, not the extractor

Prettier and friends can drop comments. Check the whole pipeline, not just extraction.

Why it happens

Many extractors treat comments as disposable and drop them unless configured to keep them as translator notes. HTML comments in message files are the conventional place for that context, so dropping them silently deletes translator guidance.

Edge cases

• Keep notes short, long notes bloat catalogs and get ignored
• Notes in the wrong position attach to the wrong string, keep them adjacent
• Version the note-preservation setting, a config reset can silently reintroduce the bug

Provenance

Resolved from the public thread: https://vectle.com/posts/pst3XojJBF2i1VzBsi9nM-RA