Rework help text for UI translations and importing po files

I'll look at this one.

Updated issue summary.

Text change from Kristin Tkoch (@K2-hook42) for admin/config/regional/translate/import:

For custom situations where translations need to be manually imported, this page imports the translated strings contained in a Gettext Portable Object (.po) file. 

You can customize .po files offline by editing them in a Gettext translation editor, then importing them here. Templates of original language .po files can downloaded from the Drupal translation server.
 
Importing an individual .po file may be a lengthy process.

I'm checking the code for any other places that we might need to change.

I've integrated this help into a patch to change the text on this page. I would recommend keeping it to 2 paragraphs, the first one about importing .po files and the second about how to go about producing .po files for Drupal.

There is also some text in the INSTALL.txt file that needs work or maybe this should just be removed:

2. Optionally, download a translation.

   By default, Drupal is installed in English, and further languages may be
   installed later. If you prefer to install Drupal in another language
   initially:

   - Download a translation file for the correct Drupal version and language
     from the translations website providing your translation files. By default,
     the Drupal translations website provides these files:

     http://localize.drupal.org/translate/downloads

   - Place the file into the dedicated translations directory. By default this
     directory is:

       sites/default/files/translations/

     If the directory doesn't exist, you should create it. Make sure your file
     is named drupal-VERSION.LANGCODE.po (for example, the German
     translation for Drupal 8.0 should be named drupal-8.0.de.po).

   For detailed instructions, visit http://drupal.org/localize

Updated issue summary.

Updated issue summary.

I'm making a patch that removes section 2 and adds a small new section after the multisites section.

Attached a patch. This is a combination of pixelite's patch and changes to the INSTALL.txt file.

How about changing:

You can customize .po files offline by editing them in a Gettext translation editor

to

Custom .po files can be created by editing them in a Gettext translation editor

?

Getting rid of "original language" seems fine.

How about switching the order of the sentences... download them first and edit them afterwards:

Template .po files can downloaded from the <a href="@url">Drupal translation server</a>. These can be customized by editing them in a Gettext translation editor. 

What about the export/import stuff?

Default .po files can be downloaded from the <a href="@url">Drupal translation server</a> or <a href="@export_url">exported from the site</a>. The .po files can be customized by editing them in a Gettext translation editor, and then can be <a href="@import_url">imported into the site</a>.

This could be made into one sentence:

Default .po files can be downloaded from the <a href="@url">Drupal translation server</a> or <a href="@export_url">exported from the site</a>, then customized in a Gettext translation editor, and <a href="@import_url">imported into the site</a>.

Tested and works, text makes sense to me, and code looks good. Since I helped with the patch, maybe I can't RTBC? I will anyway ;)

Overall, I like this but I have two questions:

1. Is the first sentence of the help text telling me that normally I shouldn't have to use this screen? If so, I think we could be even more explicit about it.

2. As a user, what am I supposed to do with "it may be a lengthy process"? It sounds scary and I'm not sure it is all that useful to know. I'm not sure how to act on that information. I guess it is telling me to be patient?

Thanks for the review, @Dries!

Regarding 1: Yes, they don't normally need to come here unless they have custom strings. Perhaps something like:

This page is only needed when importing custom interface strings. The translated strings must be contained in a Gettext Portable Object (.po) file.

Regarding 2: This text was there before, but, yeah, it does sound scary. The upshot is that it might take awhile to import the strings in. So, "be patient" is good ;) Perhaps something along the lines of:

Importing an individual .po file sometimes takes awhile for it load into the system.

I don't like that wording but something to indicate that you shouldn't stress if the import is taking awhile, i.e. "be patient".

Just wondering... when is someone's situation custom or not? I think For custom situations where translations need to be manually imported, could be simply put like this... If translations need to be manually imported,

Oh and due to #18 and #20... this is needs work

@alexpott - Do you have any feedback on the wording for item 2 in #19? I was hoping to get feedback before changing it.

I've included a patch with some new wording.

If translations need to be manually imported, this page imports the translated strings contained in a Gettext Portable Object (.po) file. Be patient as it may take awhile for some imported .po files to be processed by the site.
Default .po files can be downloaded from the Drupal translation server or exported from the site, customized in a Gettext translation editor, and imported here.

As a user, I miss the information about custom translations. Maybe this will help or makes things more complex?

This page imports the translated strings contained in a Gettext Portable Object (.po) file. In some situations, translations could need to be manually imported, like if you want to customize a translation and don't update it automatically from the default source. Be patient as it may take awhile for some imported .po files to be processed by the site.
Default .po files can be downloaded from the Drupal translation server or exported from the site, customized in a Gettext translation editor, and imported here.

What about this:

This page allows translators to manually import translated strings contained in a Gettext Portable Object (.po) file. Manual import may be used for customized translations or translation of custom modules or themes. To customize translations you can download a translation file from the Drupal translation server or export translations from the site, customize the translations using a Gettext translation editor, and import the result using this page.

Note that importing large .po files may take several minutes.

I've created one paragraph about the use of this page, and about customized strings. The notice about the duration of the import is moved into a separate paragraph, since it is a separate subject.

Most excellent! Thanks @Sutharsan for the clear and helpful wording :)

Unassigning ;)

+++ b/core/INSTALL.txtundefined
@@ -384,6 +365,14 @@ settings, consult http://drupal.org/getting-started/6/install/multi-site
+For detailed instructions, visit http://drupal.org/documentation/multilingual
+
 MORE INFORMATION
 ----------------

+++ b/core/modules/locale/locale.moduleundefined
@@ -166,7 +166,8 @@ function locale_help($path, $arg) {
+      $output .= '<p>' . t('This page allows translators to manually import translated strings contained in a Gettext Portable Object (.po) file. Manual import may be used for customized translations or translation of custom modules or themes. To customize translations you can download a translation file from the <a href="@url">Drupal translation server</a> or <a href="@export">export</a> translations from the site, customize the translations using a Gettext translation editor, and import the result using this page.', array('@url' => 'http://localize.drupal.org', '@export' => url('admin/config/regional/translate/export'))) . '</p>';

I think we need some commas:
Manual import may be used for customized translations, translation of custom modules, or themes.

Thanks for the review!

Hmmm.... not sure I agree. The way this reads:

Manual import may be used for customized translations, translation of custom modules, or themes.

It makes it sound like it can be read as:

• Manual import may be used for customized translations.
• Manual import may be used for translation of custom modules.
• Manual import may be used for themes.

The first two are fine. The last doesn't sound right ;)

What about:

Manual import may be used for customized translations or for the translation of custom modules and themes.

?

Yeah it intended to mean custom modules and themes AFAIS indeed.

I've updated the wording with my suggestion in #29.

Drupal\user\Tests\UserPasswordResetTest
One-time link is no longer valid.
UserPasswordResetTest.php 81 Drupal\user\Tests\UserPasswordResetTest->testUserPasswordReset()

This looks like unrelated failure.

#31: drupal8.translation_download_text_changes.1861934-31.patch queued for re-testing.

All green... would love a RTBC :)

$output .= '

' . t('Note that importing large .po files may take several minutes.') . '

';
return $output;
I like the suggestion to add a "Please be patient." (#18, #19) to the last sentence.

I tried to follow the instructions of the help text to see if they are useful. I have a minor experience of using .po files a long time ago but I think that if I hadn't have any experience I would have been much more unsure. Now everything went more or less ok, besides a couple of errors that are not related to this issue.
____________________

The unrelated errors:

1.) After exporting the translation from the site, I got an error message that is documenter in this issue: #1789090: Warnings when exporting templates: addcslashes() expects parameter 1 to be string

2.) After importing the .po file, I got this warning message (I didn't find an issue for it):

An AJAX HTTP error occurred.
HTTP Result Code: 200
Debugging information follows.
Path: /drupal/batch?id=6&op=do_nojs&op=do
StatusText: OK
ResponseText: Recoverable fatal error: Argument 2 passed to Drupal\Component\Utility\String::format() must be of the type array, null given, called in /Users/outimunter/Sites/drupal/core/lib/Drupal/Component/Gettext/PoStreamReader.php on line 522 and defined in Drupal\Component\Utility\String::format() (line 89 of /Users/outimunter/Sites/drupal/core/lib/Drupal/Component/Utility/String.php).

The translation was anyway imported.
____________________

Next, I'm going to make the patch asked for in #37.

Thanks @Outi! Would you report issue 2 from #38 once you are done updating this patch? :)

I added the "Please be patient" suggested on the #37.

Moving back to RTBC as per fixes since #28.

Discussed in person that "please be patient" is the kind of wording that we worked on removing earlier. The prior sentence explains the situation well. So #31 should be RTBC then.

Committed 2faba60 and pushed to 8.x. Thanks!

See #1970068: Remove all please(s) from the views UI about using please in the UI

I reported it here: #2029505: Exporting translations does not correctly generate empty strings