translate: a way to mark a block as required-verbatim, so a legal notice survives the Chinese build

[chideat]

What we need

A way to mark a block within a page as required-verbatim, so doom translate copies it through unchanged instead of translating it.

The case is a trademark notice. Our product's compliance rules require a specific two-paragraph English statement, reproduced word for word, and they require it to survive on the Chinese site: the English must remain, in English, and a translation may only be appended after it. That is not a style preference we can concede.

What happens today on our Chinese build is that the statement is translated and the English paragraphs are dropped entirely, which is exactly the outcome the rules forbid.

Why additionalPrompts is not a solution

We tried it. The page carries an i18n.additionalPrompts block telling the model to keep those paragraphs in English, verbatim. Two things in the template work against it:

1. The additional requirements are introduced with "in case of any conflict, the baseline requirements should take precedence", and the baseline is what says to translate the document. A "do not translate this" instruction is, by that sentence, explicitly subordinate to the instruction it needs to override.

2. In 1.12.1, which is what our docs repository pins, the block is preceded by "The text for translation is provided below, within triple quotes:" and the prompts are placed inside those triple quotes. The user's instructions are handed to the model under a label saying they are the text to translate. This one looks already fixed on main; I mention it because repositories still on 1.x are affected and may not know to upgrade.

Either way, the result is a probability, not a guarantee, and we cannot verify a legal notice by rebuilding and hoping.

Why masking is the right home for it

translate-mask.ts already does exactly this job deterministically, and its own doc comment makes the argument better than I can:

This generalises the code-block mechanism that has been in helpers.ts (and in production) all along; the prompt-level "do not touch links" instructions it replaces were detailed, and documents still came back with rewritten links.

That is the same lesson, on the same mechanism, for the same reason. Links got a placeholder because instructions did not hold. A required-verbatim legal notice has a stronger claim to one than a link target does, and the machinery is already there: an opaque placeholder, a count checked on the way back, and a restore step.

Suggested shape

A MaskKind for an author-declared region, delimited by a comment pair, in the spirit of the reference-start / reference-end markers already recognised:

<!-- doom-verbatim-start -->

Valkey® is a registered trademark of LF Projects, LLC.

Alauda is an independent vendor. This product is not affiliated with, endorsed by, or sponsored by LF Projects, LLC.

<!-- doom-verbatim-end -->

Everything between the markers is masked before the call and restored after, so the model never sees it. The markers themselves would be removed from the output, like reference-start.

We are not asking for the appended-translation half to be automated. If the block comes through untouched, we can put the approved Chinese rendering in the source next to it.

What we could not use

• i18n.disableAutoTranslation turns off the whole page. Our intro page is the one page that most needs translating; only three paragraphs on it must not be.
• translate.copyOnlyDirectories is directory-level, and the same objection applies.

Environment

@alauda/doom 1.12.1 for the affected repository; the template quoted from main is 2.8.0. Happy to test a build, and happy to open a pull request against translate-mask.ts if the shape above is one you would take.