@Cpiral: I got lost reading this. :(
Is there's a bug described, some feature request, or some general request to discuss about "Translation markup for editors" which is better suited for a mailing list or discussion page?

Structuring this task is welcome (you can edit a task description in Phabricator): What are 1) Steps to reproduce the problem, 2) Expected outcome, 3) Actual outcome ?
Also see https://www.mediawiki.org/wiki/How_to_report_a_bug - thanks!

I edited the task description. Hope that helps.

The scope and affect of the missing documentation I describe seems like a "Phabricator bug" in project "Documentation" to me.

Perhaps I'll try Help talk:Editing as well. Thanks for your considerate response Aklapper.

@Cpiral: Thanks for editing!

Current documentation is oriented

Where is that current documentation that you looked at and that was not sufficient? You've mentioned "Help:Editing", could you provide a link to that? Any other documentation you refer to?

Would https://www.mediawiki.org/wiki/Help:Extension:Translate/Page_translation_administration#Changing_the_source_text and https://www.mediawiki.org/wiki/Help:Extension:Translate/Page_translation_example#Step_4:_Making_changes be helpful information?

(And I'm wondering whether in the long run, dealing smoothly with translation markers in VisualEditor (which requires T50891: Parsoid should support <translate> and <tvar> natively as they are not normal parser tags to get fixed) is the solution. To not see such markers anymore.)

I've read and reread the sections

• Changing the source
• Making changes
• Glossary
• Segmentation

and although the glossary started to help, I still experience failure, discomfort and feel at a loss while editing around translations, which I have done for months at Help:CirrusSearch

Translations is a whole new layer to wikitext, and we must try harder to help editors understand how exciting and wonderful and important it is to learn to work with it. But currently translators seem like site-administrators with special permissions, training, and powers over wikitext and editing, having there own language and documentation.

To grow these two major areas together is important. It was inevitable that they started apart, for they are both great big. Currently editors lack there own ground for translations markup, from which to grown towards translations in its own right.
Care and direction must be shown by someone who knows both MediaWiki web-page and MediaWiki translations markup, and writes the page.

Here are some links for examples. (Sincere thanks go to Nemo and Shirayuki. Please forgiving me, and let me use these as examples.)

• Translators ignore editors
• Translators are trigger happy, starting up the process on a known-unstable-growth-stage page.
• Translators exercise there special additions, but don't participate in the actual content. Shirayuki on Help:CirrusSearch is the main "editor", but only by virtue of translations or undoing vandalism.

Hopefully it will become true sooner than later that editors get there own care and feeding concerning every single tiny aspect of translations, full and complete coverage on one page so that they can edit, at will, any editable page and have a quick-ref.; and know that policy is set in place towards the expectation that

• gives editors get unfettered assistance from translators
• gives editors the final say and determination when translations are needed, wanted or unwanted
• encourage translators to earn their privilege on each page by first contributing significantly to content, and proving they understand the "larger world" they claim to administer.