Background:
This issue is part of the task to update the hook_help texts of the Drupal 8 modules:
#1908570: [meta] Update or create hook_help() texts for D8 core modules

Tasks:
a) [done, patch attached] review / write the hook_help text according to help guidelines

b) (novice) Final manual testing
1. Apply the patch.
2. Go to admin/help.
3. Click on the help page for this module (Content Translation).
4. Verify that the help page is OK:
- Verify that all the links work
- Verify that all mentions of pages/text/permissions within the UI match what is seen in the UI
- Verify that the formatting is OK.

Comments

Title:Update hook_help for Translation Entity moduleUpdate hook_help for content_translation module

Module name changed.

Status:Active» Needs review
StatusFileSize
new3.73 KB
FAILED: [[SimpleTest]]: [MySQL] Invalid patch format in drupal8.documentation.2091479-2.patch.
[ View ]

Assigned:Unassigned» vzblk

Status:Needs review» Needs work

The last submitted patch, drupal8.documentation.2091479-2.patch, failed testing.

StatusFileSize
new3.71 KB

Status:Needs work» Needs review
StatusFileSize
new3.71 KB

StatusFileSize
new3.71 KB
PASSED: [[SimpleTest]]: [MySQL] 58,581 pass(es).
[ View ]

Status:Needs review» Active

Status:Active» Needs review

Testbot expects *.patch files, but *.patch.txt given

StatusFileSize
new3.71 KB
PASSED: [[SimpleTest]]: [MySQL] 59,019 pass(es).
[ View ]

Status:Needs review» Needs work

Thanks for the patches, and sorry for the delay in reviewing -- the help sprint was so successful, I have been having trouble catching up!

The help for this module needs some more work besides what is in this patch:

a) The reference to the on-line documentation in About is not following our guidelines:
https://drupal.org/node/632280
b) In "enabling translation" in Uses, second paragraph, we should have the link text be the actual page title. So it should say something like "After adding languages, configure translation on the (link)Whatever whatever whatever page(end of link)." and have the "whatevers" match the actual page title. This also needs to be fixed in the Permissions item in Uses.
c) Our standard in Drupal is to use serial commas in lists, such as "dogs, cats, or horses". This comma is missing before and/or in at least one case (in Translating Content). Check for other cases too?
d) When using apostrophes in text, enclose the entire text in double quotes rather than using \' to escape the quote. (That applies to Changing Source Language).

Issue summary:View changes
Status:Needs work» Needs review
Parent issue:» #1908570: [meta] Update or create hook_help() texts for D8 core modules
StatusFileSize
new5.36 KB
FAILED: [[SimpleTest]]: [MySQL] Unable to apply patch update-hook-help-content-translation-2091479-12.patch. Unable to apply patch. See the log in the details link for more information.
[ View ]

The file was changed and we can not apply old patch, so we did not create interdiff.
Fixed issues from comment #11.

Status:Needs review» Needs work

The last submitted patch, 12: update-hook-help-content-translation-2091479-12.patch, failed testing.

Status:Needs work» Needs review
StatusFileSize
new5.36 KB
PASSED: [[SimpleTest]]: [MySQL] 59,879 pass(es).
[ View ]

Status:Needs review» Needs work

Thanks for the rerolls... The patch still needs some work:

1. One thing I forgot in the last review: We don't actually want to use the word "Drupal" in any text inside Drupal, as much as possible. See https://drupal.org/node/604342 under "Wording".

2. It looks like item (a) from #11 has not been addressed.

3. Regarding #11 (c) the commas are still not right. See http://grammar.about.com/od/grammarfaq/f/QAoxfordcomma.htm

Specific examples:
- "From there, you can add translations and edit, or delete existing translations."
===> there should not be a comma before "or" here -- it is not a list.
- "This process is similar for every translatable element on your site, such as taxonomy terms, comments or user accounts."
===> There should be a comma before "or" here, because it is a list.

4. The "Maintaining Translations" Uses header was dropped in the latest patch.

5. There are still some calls to url(). See https://drupal.org/node/632280#url-note

Status:Needs work» Needs review
StatusFileSize
new6.23 KB
PASSED: [[SimpleTest]]: [MySQL] 63,715 pass(es).
[ View ]
new5.87 KB

Tried fix all issues.

Status:Needs review» Needs work

Much better, thanks!

There are still some issues:

a) There is no module called "Locale" in Drupal 8. The module whose machine name is "locale" is now called "Interface Translation", and there is a separate module whose machine name is "language" that is called "Language". The "About" text referring to the "Locale" module is not accurate any more -- the Language module is where you configure languages, and the "Interface Translation" module is what lets you translate the user interface.

b) When referring to this module, it should be called "the Content Translation module" (note the capitalization).

c) Check the help standards (https://drupal.org/node/632280) for the standard way to link to the on-line docs. Still isn't right. Also it seems to be linking to http://drupal.org/documentation/modules/translation_entity -- it should be http://drupal.org/documentation/modules/content_translation, and if that doesn't exist, we should create it.

d) We seem to have lost this Uses item in this patch:

-      $output .= '<dt>' . t('Maintaining translations') . '</dt>';
-      $output .= '<dd>' . t('If editing content in one language requires that translated versions also be updated to reflect the change, use the <em>Flag other translations as outdated</em> check box to mark the translations as outdated and in need of revision.') . '</dd>';

Is there a reason for that? It seems like good information.

I'm working on this.

Status:Needs work» Needs review
StatusFileSize
new3.75 KB
new6.36 KB
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 66,810 pass(es).
[ View ]

I've made the following changes sugested by @ jhodgdon:

a) Updated 'locale' references to 'Interface Transation' and I splited Language and Interface Translation mention at 'About'.
b) I updated references to 'Content Translation module' to capital letters.
c) I Updated the link to Content translation Drupal.org documentation. There isn't a page at Drupal.org documentation for Content Translation module, we should create it.
d) Added 'Maintaining translations' section to the patch.

Thanks to @jhodgdon for review it.

Status:Needs review» Needs work

Thanks -- looking pretty good! A few mostly minor things to fix:

a) Translating bullet point:

...tab or link that will gives an overview of the translation status...

take out "will" here.

b) In the Changing source language bullet point... I wasn't sure what this referred to. Is this when you are already in the middle of translating an item? If so, maybe start the text with "When you are translating content, if there are two or more..."?

c) In the Permissions section... So, the first sentence says that the module gives you basic permissions, but doesn't explain what they are or what they do. Then the next sentence says there are also additional permissions, and says that these can be configured on the Permissions page, which kind of implies that the basic ones can't? So... I just think this is kind of confusing.

d) "translatable element"... hmmm... The About section says the module lets you translate "content", and the word "content" is used for a while. Then suddenly the text starts talking about "translatable element". ?!? What is this? We should probably just use the word "entity", which we are using in other help text? And we should use the same terminology throughout, I think?

jbellio - I'm working on it in room Magratea now. Find me there or on IRC if that overlaps with something you are doing at the moment.

Status:Needs work» Needs review
StatusFileSize
new7.17 KB
new7.49 KB
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 66,851 pass(es).
[ View ]

I've taken up the comments above.
I've also added the Configuration Translation in the About section to make it complete.

Added a section about field level translation. There is a usability issue there, because contrary at least to my expectation, fields that are not checked as translatable show up on the translation form, and if you edit them they just change all translation instances of that content. I had assumed that they wouldn't show up, and ended up overwritting my content. That's why I made that clearer in the Uses section, but I hope that can be changed further - in which case the help text will need to be changed.

I've deleted the Permissions use because there isn't anything different from permission settings of any other module.
And I've changed the title of "Maintaing translation" to "Flagging translations as outdated" to make it more obvious.

Also changing the links for modules that don't have to be enabled.

Status:Needs review» Needs work

I've just noted that we forgot to cover the "Content language detection" on /admin/config/regional/language/detection

Good stuff!

I reviewed the patch.

Formatting is Okay

I would propose some rewriting, though:

a)

The Content Translation module allows content to be translated into different languages.
.Working with the Interface Translation and the Configuration Translation modules (which provide translation for the site interface and configuration if they are enabled) and Language module (which manages languages), the Content Translation module is key to creating and maintaining translated site content.

This is difficult to read and contains bits of marketing-speak. How about:

The Content Translation module allows you to translate content. It complements the Configuration Translation and Interface Translation modules that allow you to translate configuration text and built-in interface text.

b)

You then need configure which content entities

should be:

You then need to configure which content entities

c)

In order to translate content, there must be at least two languages listed on the Languages page. You then need configure which content entities can be translated on the Content Translation page. For more information on languages, see the Languages help page.

I would write:

In order to translate content, you must have at least two languages enabled. Then you can define which content entities can be translated on the Content Translation page.

With links on the words "languages" and "Content Translation" and given the complexity of the concept, I would put a link to the entity help page on "content entities"

d)

If you exclude a field, it still shows up in the translation form, but any edits made to that field will be applied to all translations of that content.

I would put

If you exclude a field, it will still show up in the translation form, but any changes made to that field will be applied to all translations of that content.

e)

Then, you will see a Translate tab or link

Why these 2 situations? Is it not always a tab?

Component:documentation» content_translation.module

Changing component and linking this to #1188388: Entity translation UI in core to get feedback from maintainers.

+++ b/core/modules/content_translation/content_translation.module
@@ -24,27 +24,26 @@ function content_translation_help($path, $arg) {
       $output .= '<dt>' . t('Translating content') . '</dt>';
-      $output .= '<dd>' . t('After enabling translation you can create a new piece of content, or edit existing content and assign it a language. Then, you will see a <em>Translate</em> tab or link that will gives an overview of the translation status for the current content. From there, you can add translations and edit or delete existing translations. This process is similar for every translatable element on your site, such as taxonomy terms, comments or user accounts.') . '</dd>';
...
+      $output .= '<dd>' . t('After enabling translation you can create new content, or edit existing content by assigning it a language. Then, you will see a <em>Translate</em> tab or link that gives an overview of the translation status for the current content. From there, you can add translations and edit or delete existing translations. This process is similar for every translatable content entity on your site, such as taxonomy terms, comments, or menu links.') . '</dd>';

"After enabling translation you can create new content, or edit existing content by assigning it a language. "

by assigning, does not make sense.
also I think this is left over from before.
we do not need to edit existing content and set a language for it. now, all content has a language.
also, the ability to change the language of content is provided by the language module, not the content translation module.

Assigned:vzblk» batigolix

i take this

Batigolix: take #23 into account - we forgot the interface language detection methods based on the content language

will do! need some time though. devdays have drained my batteries

Status:Needs work» Needs review
StatusFileSize
new7.46 KB
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 67,040 pass(es).
[ View ]
new7.63 KB

Batteries reloaded! Let's wash this piglet (well known Dutch expression)

Attached patch addresses the points made in #24 and #26.

a) I should apologize to Ifrik for drastically changing her work, but the only way for me to fix some bits was by changing its context and this lead to a complete rewrite. In its core it is still your text, though ;)

b) I cannot reproduce the section under "Changing the source language for a translation". You have a screenshot or URL where I can see this at work?

c) I encountered some pretty funky UI texts when working on this hook_help. We need to notify the UX team about this possibly postpone this issue until this has been fixed. We already discussed this in Szeged.

d) Maybe we should use a common introduction for all the 4 modules of the multilingual suite?

e) Given the drastic changes, I expect a couple of grammatical and spelling error, so this needs a decent review.

Status:Needs review» Needs work

Hm. I'm not sure I want to wash any piglets, but I've at least reviewed the patch. :)

Proofreading:

a) in About:
... Configuration Translation[needs comma here!] and Interface Translation[comma here!] it allows

b) In Field uses bullet point:
... Typically you want to translate the title and body field while leaving the image field untranslated. ...
I think here we should maybe say "For example, you might want to..." instead?

c) In Translating Content bullet point:
... Translation tab (or Translation link). The Translations page ...
Um. Is it Translation or Translations? Hm... in the UI that I see, for Content (node) items anyway, the tab is calleld "Translate".

d) Same point:
...add, edit[needs comma here!] and delete its translations...

Also...

e) I like your idea of making all of the language-related modules have similar About sections.

f) I tried out the "source language" stuff too. What I did:
- Enabled Content Translation and Language modules.
- Added French and Spanish
- Set up Page and Article nodes as translatable
- Created a page in English.
- Translated it to French.
- Clicked Translate again, and then clicked Add for Spanish.
- Near the top, there is a collapsed fieldset with title "Source language: English". I can open this and it allows me to change the source language to French. And as stated in the help, after saving the source language I chose does show up in the Translate tab.

So... I would suggest the following wording for this bullet item:

When you add a new translation, the original text you are translating is displayed in the edit form as the source. If at least one translation of the original content already exists when you add a new translation, you can choose either the original content (default) or one of the other translations as the source, using the form at the top of the page. After saving the translation, the chosen source language is then listed on the Translate tab of the content.

Status:Needs work» Needs review
StatusFileSize
new7.53 KB
PASSED: [[SimpleTest]]: [PHP 5.4 MySQL] 66,976 pass(es).
[ View ]
new6.47 KB

Patch that addresses point in #31:

a) done
b) done
c) the tabs is named Translate, the page is named Translations (done, but this might need to be adjusted after a UI string review)
d) done
e) OK. keep in our minds for the other 3 language modules, with the About of Content Translation as a model
f) Ok, I see this now in action after I enabled a 3rd language. Not the prettiest UI. I changed the wording a tiny bit to prevent having to say "on the top of the page" as such element can be easily replaced

Looks good! I think this is ready for a manual test:
- Verify that all the links work
- Verify that all mentions of pages/text/permissions within the UI match what is seen in the UI
- Verify that the formatting is OK.

Issue summary:View changes

Updated issue summary to make clear what the remaining (novice) task is.

Issue summary:View changes