String freeze: Locale module

I started work on the text in locale.module, but a patch here would conflict badly with http://drupal.org/node/175876, so I'll wait a bit and see if that patch makes it in.

A few remarks about this patch:

• This was simply the first issue without a patch that showed up in the documentation component queue, and in an attempt to work through all of those issues over the next several days, I picked it first. I wasn't trying to pick on poor locale module.
• I freely admit that I do not know much about the locale module, and therefore, please be very careful when reviewing this patch as I may have misrepresented functionality.
• Having admitted that I do not know much about the locale module, let me express my amazement at what it now does. After going through all the help text that I could find related to this module, with the notable exception of content translation, I have a newfound respect for the i18n work that has gone into Drupal 6. Gabor, Jose, and everyone else that has worked on this deserve a big pat on the back. I didn't realize that locale module did all that it does, and let me tell you: it does a lot.
• There are a few places where I would have reworded some things, but I couldn't quite figure out what they meant. One specific place is in the Language negotiation radio box, for instance; the description on "None" completely eludes me. It seems to me that "None" would be the one option there that would be dependent on visitor preferences -- if your site is set to none, don't users still get to select the language they would like to use? I must be not understanding something.
• This should be set to CNW, due to instances like the the one I just mentioned, but I'm setting it to CNR to get some feedback.
• In the installer, we introduce the concept of a translation pack, but as nearly as I can tell, never reference that again. I tried to expand the text to build on that term as an accepted Drupalism. If we do not want to use that term, we should simply remove it from the installer text.

So, please review!

thanks Gábor!

I know this one is a pain to review, especially when I don't quite [yet] understand what everything is doing. I appreciate your patience.

I:

-- fixed the missing strong tag.
-- reworded the negotiation sections from above, taking your advice and restoring the "fun" examples (which actually are more illustrative). After thinking about it, is is likely that this section did not do exactly what I thought it did -- I now think it does something very simple, elegant and powerful: allow the user to input a variable string that, when matched within a displayed link, selects that language.
-- reworded LANGUAGE_NEGOTIATION_NONE based on your comments above.
-- fixed my error on the "This block is only shown if your site display language is determined..." string.
-- reworded the "Path aliases used to select a site display language take precedence over all other aliases..." string to say "A path alias set for a specific language will always be used when displaying this page in that language, and takes precedence over path aliases set for All languages."

After sitting on this for an hour or three, I found a few inconsistencies in my earlier patch. New patch attached. This version is untested, however.

thanks for your comments, Gábor -- I learn a bit more about this every time I read one of them.

The attached patch adds in the note from #6, and dramatically modifies the /admin/settings/language/configure screen (screen shot attached). This may be an unorthodox way to provide an explanation for the setting on this page in this manner, but:

-- this is a complex radio button, and there is no good way to provide the information needed actually on the options themselves.
-- I've already seen at least one and possibly two issues about the longer options being cut off as they passed the left margin, as they do not appear to wrap. Moving the explanatory text into the help text above prevents this.

@9: In the attached patch, I hope that I adjusted the delimiters properly, but a review is always helpful. Thank you for your comments.

@8: Thanks especially for your comments!

-- I've standardized on "translation packages" at your suggestion, and this patch includes modifying text in install.php to that end.
-- I've added a brief mention on the /admin/settings/languages page to indicate that the enabled languages are also used when creating posts of multilingual content types. If I need to add additional language to tie this in to the translation module I will be happy to do so.
-- /admin/build/translate/import should now explicitly note that import is for a single .po file that needs to occur in non-automatic-import time.
-- On exporting template files, I've modified the text on the /admin/build/translate/export page to reflect that a template file export is useful in creating new translations in the form of .po files.

Following up on this last point, though:

is this text correct: For translation tasks involving many strings, it may be more convenient to export strings to a desktop Gettext translation editor. Should this say, uh: To create a new translation, it may be more convenient to export a template file containing the original strings for use in a desktop Gettext translation editor. (or something similar). I'm unclear on what these desktop editors can and cannot edit.

is this text correct: For translation tasks involving many strings, it may be more convenient to export strings to a desktop Gettext translation editor. Should this say, uh: To create a new translation, it may be more convenient to export a template file containing the original strings for use in a desktop Gettext translation editor. (or something similar). I'm unclear on what these desktop editors can and cannot edit.

Thanks for the quick reply. I understand your comment to be that if the .po file you use with the Gettext editor contains the translated version of the string, then you can use this editor to make changes in the translated version (but would then presumably have to reimport that changed file at the import page). It is only when one is using the editor to read the template version of the file that does not include the translated strings that one, of course, does not have translated strings to edit (and thus, would best use this for creating new translations).

If I understand that correctly, then the text is probably ok the way I have it. I just wanted to make sure that the editor was not used to ONLY create new strings, but that, given a translation, could edit that as well.

This is one of the few modules with help text unaffected by http://drupal.org/node/197297#comment-652207 (because I skipped those comments knowing that this issue was here).

Gabor, in #14, you mention a lot of points, thank you for the detailed review. I'm going to work on addressing some (or all) of your points over the next couple of hours, so I'm going to assign this to myself for the interim.

Gábor @ 14:

That last patch I uploaded was bunk. I was very unimpressed with it when I read through it this last time.

I have not much confidence, though, that this one is an improvement, so I'm tempted to leave at CNW. However, string freeze looms large, and this would be nice to get in, so I'm going to set it as CNR to [potentially] speed up reviews.

The language domain misleadingly suggests that it is just a "language code or..." (text seemingly copied over from the path prefix). While the path prefix is really only a language code or special text identifying the domain, the domain is not. It is actually a language "base URL", but base URL is not a concept used elsewhere on the user interface.

I attempted to address this point.

Gettext is named "GNU Gettext" at only one place. IMHO we don't need GNU there, or we need to include GNU at all places for consistency.

My brain is apparently composed largely of oatmeal. I hope that I have these consistent now. I nuked GNU. :)

I don't understand this, and expect that others might not understand as well: "language of posts with multilingual support may be indicated"

See above comment. Who knows what I meant.

Help text for admin/settings/language still says that the import page imports a translation package. This is not true. When a translation package is extracted to the Drupal source folders (in the structure as indicated in the translation package) and a new language is added, the translations for installed modules and themes are imported automatically. The import screen can only be used to import .po files one by one. With 20+ enabled modules it is much easier to extract the translation pack first, then add the language and let Drupal import the files automatically (with a nice progress bar is displayed on the screen :), instead of importing them one by one.

admin/settings/language/add help has the same problem, and it calls packages packs :)

in the admin/build/translate help, the "site translation" term seems to be misleading to me. We have interface translations, but the site can have menus, taxonomies, nodes, uploaded files, etc. which are not managed on the admin/build/translate page. Here, again, translation packs cannot be imported on the import page.

- import help: "This page allows for the import of individual Gettext Portable Object (.po) file" seems to be a typo. An s is missing from the end of the sentence? Although the second part of the text talks about automated imports, the first talks about importing packages on the web interface again :)

I reworked this stuff extensively. I feel like there are still problems in there somewhere, but I probably won't see them until after I let this rest a bit.

search: "and is used when building a new or editing an existing translation" seems like missing someone around "new"

hopefully fixed.

BTW: thanks for the Hungarian translation package. I downloaded, extracted and added it, and everything imported fine. I played around with it a bit -- this is all very neat. One thing I did notice -- I seemed to only be able to mark the language of a post when creating new content, not when editing existing content (i.e.: I had some example pages on my site prior to adding the language, and after enabling multilingual support : Enabled with Translation, I could specify a language on new pages but not previously existing pages. This is probably the way it is supposed to be, but I should probably make sure my help text, above, reflects that distinction.

Edit: Ignore me. I tried this again (editing a page), and it worked fine. May have been a caching issue or something.

*sigh*

I apparently cannot get this patch completely right. I just read through the patch in #16 and found what is hopefully the last reference to "translation pack". I fixed that, and corrected two or three small issues with word flow.

The attached rerolls the prior one so that it will apply, and makes the following changes:

There is a "translation pack" instance still here: "automatically import files from a translation pack"

fixed. I apparently just can't find those. I even used a search on the earlier patch, and still didn't see it, apparently. :)

This sentence seems to be too "determined" :P "Language negotiation settings determine how the site's presentation language is determined."

bleh. fixed.

Maybe admin/build/translate/import elaborates on what a translation package is too much? Also first it explains what is in it, and then explains it generally, quite strange.

Quite strange indeed; now fixed. I took out most of that last section, so hopefully this is less weird.

What I have not done yet is this:

The main help on admin/help#locale still only talks about interface translation, while this module provides the language association for nodes and paths aliases, as well as as language negotiation for incoming requests; these should be mentioned

so I'm going to leave this at CNW.

The language negotiation I get, I think, and should be included. I am not 100% certain about the last part of your note, though. When you say "language association for nodes and path aliases", you're meaning the ability to have language-specific aliases, and to note the language that a particular node is authored in? Or something else?

Please don't apologize -- indeed, the fault was mine. I had the [mistaken] idea that this was handled by translation module.

This patch adds the following text to the locale module help:

Beyond translation of the Drupal interface, the locale module provides a feature set tailored to the needs of a multi-lingual site. Language negotiation allows your site to automatically change language based on the domain or path used for each request. Users may (optionally) select their preferred language on their My account page, and your site can be configured to honor a web browser's preferred language settings. Your site content can be created in (and translated to) any enabled language, and each post may have a language-appropriate alias for each of its translations. The locale module works in concert with the content translation module to manage translated content.

And, since locale module links to translation module help, I added a link in translation module help back to locale module.

Please review.

none should be None.

Oh. My. God.

I was about to suggest that we "won't fix" this to save you the time and trouble. Thanks for reviewing it again, and thanks especially for sticking with me on this one -- locale and content have a large feature set, and some of them are not immediately obvious to those of us who do not run multilingual sites. This issue has convinced me, though, that locale and translation are the unsung heroes of the Drupal 6 release. I guess everyone else already knew this, but I'm really amazed at what they do. Everyone involved in those modules should pat themselves on the back.

I know I've been spending a lot of time on help text lately, as have other folks. I'm pretty happy to be doing that, because I think about translators -- and what they do -- and shake my head with some amazement. I say this having written some very confusing bits here and there: there are places in Drupal where I have to read the English version two or three times to figure it out. That a translator can read it (sometimes with limited English skills), determine what it is *supposed* to say, and then properly translate it to another language is pretty impressive.

I do pretty much believe that no one reads help text, but obviously translators do -- it would be very interesting to get feedback on what areas of the interface are (especially) hard to translate, so that we can take a second look there. That may already be a feature of the localization server (which I've only recently started following).

Anyway -- thanks Gábor!