I fought with <!--T:NN--> on mw.org for an hour last week. Thanks to Nemo_bis I figured it out but it was rough.

https://www.mediawiki.org/wiki/User:SPage_%28WMF%29/Sandbox?oldid=1682729 explains my problem: I saw
<!--T:2-->
For an introductory guide to developing MediaWiki, ...

<!--T:3-->
For help installing or customizing MediaWiki, ...

and wanted to make them bullet points.  Whitespace ends a bulleted lists, so I did the right thing with the wiki markup and changed to
<!--T:2-->
* For an introductory guide to developing MediaWiki, ...
<!--T:3-->
* For help installing or customizing MediaWiki, ...
and went straight into the hell of "Multiple translation unit markers for one translation unit" errors. It turns out that with the white space gone, this is now one chunk and so has to be one translation unit; the fix is to remove <!--T:3-->. This is a case where ignoring translation markup is impossible, you have to have detailed knowledge of it to fix a simple edit.

1) "Whitespace is required between translation unit markers" is a pretty fundamental concept, but AFAICT isn't expressed clearly anywhere. I urge someone who understands it to update some page like Help:Extension:Translate/Page_translation_example

2) It would be so nice if 'pt-shake-multiple' and other complex Special:Translate error messages had links to wiki documentation. I filed https://phabricator.wikimedia.org/T102710

Thanks for this machinery, it's powerful but can maim :)
Cheers,
--
=S Page  WMF Tech writer