Convert internationalization modules: config_translation, content_translation, locale, language module hook_help() to topic(s)

There is a test failure:

Topic locale.translate_strings is either top-level or related to at least one other top-level topic

That means that the topic locale.translate_strings either needs to have top_level annotation, or "related" annotation that relates it to a different topic that is top_level.

Also please read the Standards for Help Topics. This patch is not following the instructions and standards. It looks like you just copied the text from the module overviews in hook_help, but what we want is the help separated into Overview and Task topics, which have specific headings in them (such as not "About" and "Uses" as in this patch. The patch needs a complete rewrite. The instructions are in the issue summary here.

The error message in the test fail is:

Topic locale.overview has the correct H2-H6 heading hierarchy

This is because this topic has h2 headings (good), followed by h4 headings, which are inside of the OL list of steps. That is not very good HTML practice.

So... probably this should be separated into 3 different task topics, rather than trying to describe 3 different tasks in one topic?

Same error is still coming up now in core.translations. I'll wait to review the patch until the tests pass.

Thanks for the patches!

I took a quick look... A few thoughts:

a) The text in all the topics needs a lot of proofreading attention. If English writing is not your strong point, you might either consider working on a different issue, or maybe view the topic on a test site and copy/paste the text into a word processor that has grammar/spelling checking. (Most commercial ones do, and it is also an optional extension download for Open/Libre Office Writer too.)

b) Topic titles: Most of our current help has titles that start with an -ing verb, so please follow that pattern. Such as "Adding a language" not "Add language". Also the titles should be in sentence case, so for example, "Translating Individual Interface Strings" should be "Translating individual interface strings".

c) Don't repeat information that is in other topics. For example, in the Language Switcher Block topic, it sort of tries to explain how to place a block. But we already have a topic on that. So instead, it should say something like "Follow the instructions in (link to the placing a block topic) to place the Language Switcher block".

d) Headings in the top-level topic: check Standards for Help Topics for what the headings should be for a Section topic. Should not have one starting with "How".

e) Text that you see in the Drupal administrative interface should be in italics (EM tag), not bold (STRONG tag). I saw this problem in language.block_visibility (may be present in other topics too).

f) Some topics need more explanation. For example "Language detection and selection" topic doesn't really tell me at all what language detection and selection means, or what the different options do. This information can be in a "What is" section before Steps, or incorporated into the Goal section.

I didn't read through all the topics in detail...

Here is a new patch. I did not make an interdiff for this patch, because pretty much every line in the patch has changed, so it wasn't useful.

What I did (see also previous comments):
- Edited the topic text, titles, and headings for clarity, good English, and compliance with the Help Topic Standards https://www.drupal.org/docs/develop/documenting-your-project/help-topic-...
- Replaced <i> tags with <em> tags throughout.
- On the top-level topic, changed the title to "Working with languages and translations", since the topics are useful for single-language sites too (if the language is not English) (the previous title had "multilingual" in it, which seemed not the best)
- Added a "What?" section about what types of text can be translated, and an Overview section, to the top-level topic. Took out the sections on individual modules.
- Took out the topic about the language switcher block. We already have a topic on placing blocks, so we don't need this. Instead I mentioned the existence of this block in the top-level topic and linked to the block place topic as Related.
- Took out the block visibility topic -- we already have a configuring blocks topic, so linked to that instead, and added a note to the top-level topic.
- Added a bunch of additional information to the detection & selection topic

I got through all of the topics except two: translating configuration and translating user interface. Those still need to be fixed up. Uploading patch so it doesn't get lost, but leaving at Needs Work. I'll get back to this tomorrow.

OK, here's the completed patch, with the last 2 topics updated.

Hm, one of the topics is failing the test (language.detect.html.twig) saying not all the text is translated, but I cannot see what text is untranslated. ???

I found the test fail; ran the test locally and found another test fail too. So, here's a new patch and interdiff.

Adding tag, since I worked on this issue at MidCamp virtual contribution day.

I do not agree with either of those suggested changes, but thanks for taking a look!

Hm... I don't think we use the term "configuration entities" in the UI anywhere... But we can think about this a bit.... Here's what the help topic currently says, in the steps section:

<li>{% trans %}Find the type of configuration you want to translate in the list, and click <em>List</em> for list configuration, or <em>Translate</em> for simple configuration.{% endtrans %}</li>
+  <li>{% trans %}For list configuration, find the specific item you want to translate on the next page, and click <em>Translate</em>.{% endtrans %}</li>

So, the UI is already distinguishing between simple configuration items that you can translate directly (the term "simple" is also used in the Config Manager module on the single import/export forms), and items that have to be "listed". Given that the term "configuration entity" is I am pretty sure never mentioned in the UI, and the word "list" is, I think calling it "list configuration" or "listed configuration" or something similar makes sense? But let's see if we can get a Usability team opinion.

Actually I think we should add information about simple vs. whatever we call it on #3095734: Convert config module hook_help() to topic(s) and postpone this issue until we do that.

We should discuss this on the Config issue instead, because it has to do with configuration, and that's where we're defining terms and giving background. I'll go over there.

This should not really be a Novice issue unless we want to recruit a group of novice contributors to follow the review instructions later.

Config module topics are done! This can be worked on now.

Here's a new patch. The only thing that was identified as needing attention since the last patch was the question of how to refer to configuration entities and configuration items, which was resolved on #3095734: Convert config module hook_help() to topic(s). So, the configuration translation topic in this patch was overhauled to reference that topic, and use its terminology.

Exciting!! The new HTML syntax tests found a problem! Here's a new patch.

Thanks for the review!

Regarding points 1 and 2, I think you are right that most users will be downloading translations of user interface text, and actively translating their site content first, and second configuration. So I have updated the order as you suggested. I also added links to our topics about content and configuration (which did not exist when this patch was first created).

Regarding points 3 and 4: We don't want to have very many top-level topics in general. The one top-level topic in this patch is core.translations, whose title is "Working with languages and translations".

Also, the "related" section is automatically bi-directional. So if topic A lists topic B as related, you will see both topic A in topic B's Related Topics section, and topic B in topic A's Related Topics section, when you view the topic on the site. Every topic in the patch lists core.translations in its related section, so I think we're good as far as making sure you can get to all the topics. (Besides that, one of the automated tests in Help Topics verifies that every topic we have is either top-level or listed as related to a top-level topic, so this idea is actually enforced by our tests.)

Anyway, here's a new patch -- see what you think!

Strange... This is what I am seeing on my dev site.

Go to the Extend page and make sure you have all 4 modules listed in the Multilingual section installed. I suspect that is the problem. The top-level page is in the "core" namespace, so you will see that topic even without the multilingual modules installed. But the others will only be visible if their corresponding modules are installed. For example, if Config Translation is not installed, the topics whose IDs (and filenames) start with config_translation will not be available.

See step 2 of the review instructions:

Turn on the experimental Help Topics module in your site, as well as the module(s) listed in this issue.

Anyway, thanks for the review! Those are all excellent points. I'll try to make a new patch in the next day or two.

Thanks again for the very helpful review! I think I have addressed all of your points, and in the process, rewrote text so it is hopefully clearer.

I did make a change there, but I guess you still didn't like the change.... Reading it again, I think you're right that some notion of before/after is good. How about this?

Great idea! Here's a followup child issue:
#3202300: Can we generate list of detection methods automatically in help topic?