The information in the internalization documentation (http://drupal.org/node/133977) is out-dated and needs upgrading. Specifically some of the sub-sections (how-to) guides containing contradicting information or no longer correct advice.
Specifically:
Tutorial - Building a multi-language site ( http://drupal.org/node/275705 ) and Menu items disappear when you change language ( http://drupal.org/node/346112 ) have very old information and seem to contradict the parent's advice at Menus and primary / secondary links ( http://drupal.org/node/313302 )
Also, I have a suspicion the advice given at Menus and primary / secondary links ( http://drupal.org/node/313302 ) is possibly no longer the suggested Best Practice way of obtaining multi-lingual primary / secondary link menus?
Comments
Comment #1
Anonymous (not verified) CreditAttribution: Anonymous commentedComment #2
jhodgdonComment #3
arianek CreditAttribution: arianek commentedhave the pages been marked with the "needs updating" status? that would be helpful, as i imagine the doc team will be combing through updating pages to d7
Comment #4
Anonymous (not verified) CreditAttribution: Anonymous commentedYes they have. Though one page, http://drupal.org/node/275705 , does not allow editing so the status cannot be updated.
Comment #5
LeeHunter CreditAttribution: LeeHunter commentedThat page (http://drupal.org/node/275705) was apparently a forum post at one time and doesn't have the status update field that other doc pages have. That's also probably why it can't be edited with the usual rights. Different content type maybe.
Comment #6
arianek CreditAttribution: arianek commentedperhaps whoever goes through and updates ought to do a little cut and paste into a new book page + reshuffle the book outline and then that one can be deleted so it's a normal editable page.
Comment #7
LeeHunter CreditAttribution: LeeHunter commentedI'm tagging this with D7 because I believe there are some changes to the localization process due to fields in core.
Comment #8
Anonymous (not verified) CreditAttribution: Anonymous commentedInstead of re-tagging can we instead create a new issue? I'm worried that by tagging it D7 no one will look at this until D7 is actually released. (i.e. Re-tagging will just cause this issue to be put on the shelf and forgotten)
There are, dare I say, hordes of people using D6 that struggle with it's various i8ln issues and idiosyncrasies. We would greatly appreciate better documentation on the currently supported version of Drupal than the promise of possible better documentation in the future.
Don't put off for tomorrow what can be done today ;)
(I'd happily volunteer for this myself but don't have the necessary permissions, nor technical expertise. If someone puts even a *very* rough bullet point doc together I am more than happy to flesh it out into a real support page, test it, and report back)
Comment #9
sylvain_a CreditAttribution: sylvain_a commentedThis comes from a request on the i18n issue queue:
http://drupal.org/node/1107112
If you are using the i18n documentation, you can help the update of this page by commenting on this issue.
I'm planning to have a look at this, this week, since there is now a more stable version of i18n for Drupal 7.
Comment #10
daniorama CreditAttribution: daniorama commentedHello, I managed to understand how blocks translation work. I enabled block translation with all filter inputs and then proceed with translating the strings the same way as with drupal core translations, but I'm not sure if the way I'm doing it is the proper way. Also it seems the menus translation is not working or at least not doing that. It would be great to have some docs about how should it be done.
Comment #11
jhodgdondaniorama: You posted the above comment on an issue discussing an update to a documentation page, but it sounds like instead you are looking for support. Please click on "Community and Support" at the top or bottom of drupal.org to locate a more appropriate support channel, such as IRC or a support forum. Good luck!
Comment #12
arianek CreditAttribution: arianek commented@daniorama - or if you can describe really specific pieces of documentation that are missing (on specific pages) you can file a new docs issue for that either in this main docs queue or the internationalization or localization issue queues.
@sylvain_a that's great :) if you need help with the technicalities, find me or gabor hojtsy online.
Comment #13
sylvain_a CreditAttribution: sylvain_a commentedAlright... I have scanned the whole handbook and come up with some reclassification that I will submit tomorrow. Before I start editing more thoroughly, i'd like to have an opinion from the leads on these issues:
ISSUE #1 (Critical)
UPDATED: I was wondering why I couldn't access Revisions on these nodes. Looks like this is the module maintainer putting up new pages in Documentation. I'll get in touch, but meanwhile is it possible to review the permissions?
Features Overview (D7): http://drupal.org/node/1113368
Multilingual Variables (D7) : http://drupal.org/node/1113374
Issue #2 (Major)
There is a subset of nodes which I can't edit, some containing shameful errors:
"Multilingual Taxonomy" : http://drupal.org/node/313268 (pictures width breaks layout and hides menu!)
"Multilingual Variables (D6)" : http://drupal.org/node/313272
Issue #3 (Opinion needed)
Drupal 7 Versioning:
- Please have a look at "Internationalization 5.x: Building multilingual sites" (http://drupal.org/node/133978) this has EXACTLY the structure a legacy version shoud have: clear, and cohesive within its version.
I know this has been discussed, but in the context of multilingual, we should really move relevant pages under "Internationalization 6.x" (http://drupal.org/node/312992). The i18n bundle of modules features has changed so much in D7 that it seems impossible to produce a cohesive handbook by mixing versions, at least here.
Thank you. I will follow up shortly with some structure suggestions.
Comment #14
sylvain_a CreditAttribution: sylvain_a commentedMeanwhile, here is a precious gem i've found at the bottom of a mile-long comment chain. This is my inspiration. This is totally why i'm involved with current documentation:
"I just begun using Drupal and was enthusiastic at first. Clean interface I said. Then I grew disillusionned when I needed documentation: same old disorganized crap as all the other open source projects I know. Took me 3 hours to figure out how to use the multilingual possibilities. Generally speaking, my comment about your doc is that there are just too many articles on the same subject, saying radically different things, just to mix people's mind more if that's possible, with the versions 5, 6 & 7 variants to boot. I think I will go back to Joomla... A.R."
http://drupal.org/documentation/modules/translation#comment-3988152
Comment #15
arianek CreditAttribution: arianek commented@sylvain: Aw terribly sad quote!!! I am about to go to sleep, so no reviewing time at the moment, but I have just provided you docs admin role, so you should have the ability to see and manage revisions, as well as edit some of those locked pages now. Will try and come back to review this later in the weekend if I have a moment!
Comment #16
arianek CreditAttribution: arianek commentedoh, and tags (maybe gabor will catch this then - we should definitely have him review as well along the way)!
Comment #17
sylvain_a CreditAttribution: sylvain_a commentedCurrent hierarchy of "Working with languages" (as of April 2nd, 2011)
Proposed Hierarchy (updated):
The first pages are important, much more than depth; With this version, within the first pages, newcomers would have cover the 2 core modules, and would be discovering a handbook for the main contributed module on the topic. There shouldn't be sub-pages inserted in-between.
Also, people wouldn't bump in D6 content, if it's not immediately reusable in D7. Let the new D7 features be first in the hierarchy, with legacy content at the bottom (D6, D5)
If you think this makes sense, get in touch with me for the details on how to implement this.
Oh, and good night everyone!
Comment #18
sylvain_a CreditAttribution: sylvain_a commentedPutting things back at their place ; )
Comment #19
Jose Reyero CreditAttribution: Jose Reyero commentedHi, I've just seen this this thread (thanks sylvain)
As we are almost done with the module D7 upgrade, I am doing a quick first pass moving legacy pages to its place and creating updated ones (dropping outdated stuff, to fill in the blanks later).
Only, about the "Upgrade to 7.x" page, I think it would be better as part of the main D7 handbook, so people don't miss it. Anyway if that's the general policy for all modules, ok.
Comment #20
sylvain_a CreditAttribution: sylvain_a commentedSince Jose has done most of the modifications suggested in #17 for i18n, I went ahead and did the following, for the other multilingual sections:
- Added "core module" in the title of Locale and Content Translation pages, to make it easier for newcomers to see what's available by default in Drupal.
- Created "Complementary Modules for Multilingual Sites (Drupal 7)" to list essential modules in multilingual site buildings.
- Created "Complementary Modules for Multilingual Sites (Drupal 6)" to dump less-used modules that were on the same book level as i18n. Most of these modules don't have a D7 version anyway, except "Translation Management".
- Under "Translating a site interface to different languages (Locale core module)", created a "Tutorial and snippets" page to dump what I consider to be edge cases. Added a warning to redirect people to the main sections.
- Minor edits.
The "Working with languages" handbook should look shorter and more cohesive now, hopefully, although a lot of copy review and technical review remains to be done.
I will do sporadic updates, but i'm unassigning myself so people can go ahead and edit where needed.
Comment #21
sylvain_a CreditAttribution: sylvain_a commentedComment #22
arianek CreditAttribution: arianek commentedJust pinged a couple people who might be able to give good input on the plans here (especially comment 17) - will give it a couple days to see if they have any feedback.
Comment #23
sylvain_a CreditAttribution: sylvain_a commentedMeanwhile, I got in touch with zirvap, the author of another multilingual resource (in the Tutorial section). Here's a parallel discussion on merging the resources in the main "Working with languages" handbook.
http://drupal.org/node/1114504
It's interesting to see this thing coming together, with more people involved. Perhaps someone like Gabor could also have a look at it now.
Comment #24
arianek CreditAttribution: arianek commented@sylvain fantastic! i actually emailed gabor + jennifer earlier, so hopefully we'll get a look from him. :)
Comment #25
Gábor HojtsyThe proposal from #17 looks great, although I'm not sure if it matches structure for other modules (re @Jose from #19).
Comment #26
sylvain_a CreditAttribution: sylvain_a commented@reyero - Yes, it makes sense to keep "Upgrading to 7.x" in the Drupal 7 handbook. I saw that you also moved "HowTos, tutorials and links" to the Drupal 6 handbook, which makes sense, since the examples are version-specific. I've edited the proposal accordingly.
The structure proposed by Jose Reyero makes sense to me, we could continue the discussion from there. The whole section (including pages on locale and content translation) would need copy review, to make it more cohesive.
Comment #27
arianek CreditAttribution: arianek commentedfantastic :)
@sylvain and @reyero - so just to be sure i get where this is at now, all of the rearranging of the pages into that structure is done, and it all just needs a review? (if so, we should set this to "needs review".
Comment #28
sylvain_a CreditAttribution: sylvain_a commentedExactly ;)
Comment #29
arianek CreditAttribution: arianek commentedJust did a quick review of the entire "Working with Languages" section, aside from the 6.x and 5.x i18n docs. Looking good overall!
- I cleaned up a whole bunch of formatting, and styling. For future, note the optimal way to write admin paths is eg.: ....on the Google Analytics configuration page (Administer > Configuration > Google Analytics or
http://example.com/admin/config/system/googleanalytics
) If you see more that don't match this (it's not a must to have both the admin path and the url, but at least make sure whichever's there is formatted that way).- The main Internationalization page http://drupal.org/node/133977 seems like it should be more visible in the section - it's a bit buried right now because of the small page that is the parent to it. Any ideas on how to get it more visible?
- Changed to docs input on http://drupal.org/node/1114016 and added widths on the imgs - but some of them are hosted on Flickr... if those are CC can someone reupload the files on the node so they're hosted on d.o? You can leave the linkthroughs to flickr, but the images should be hosted on d.o
That's all I've got for today - would be great to have someone additional (maybe from the localization team, or who works with multilang stuff a lot) to do a content/technical review on all this before we close it.
Thanks!
Comment #30
daniorama CreditAttribution: daniorama commented@jhodgdon, araniek: sry, I was busy these days and I couldn't answer. I've been using trial and error and found a working way to use it. I mentioned the problems I had because I couldn't find the solutions in the documentation :)
I've been using i18n without problems (besides views and neutral language nodes) so if I can help with it just tell me. I'm spanish therefore I can also help with the spanish docs.
Comment #31
LarsKramer CreditAttribution: LarsKramer commentedThanks to everyone for all the work done so far. I think quite some work still remains to be done, however, and not only in the i18n section. I would like to help, but before assigning mysef to this task, I'll go through all pages, and then report back here with my ideas. Until we get this task finished, I set to postponed #1249130: Move multilingual content one level up: Multilingual Guide.
Comment #32
LarsKramer CreditAttribution: LarsKramer commentedOkay, I have now looked further into this, and these are the ideas I have. If you agree, I'll go ahead and make a new issue summary.
Version related tasks:
Note: Many of these version related tasks would also be relevant to other parts of the online documentation. It seems most people don't follow the recommendations given in Online documentation structure: Versions. I think this is becoming a huge problem, because the lack of consistency makes the documentation harder to navigate and maintain. So I am thinking about making a separate issue report about how we can deal with this.
Other tasks:
Some ideas for new content:
Comment #33
jhodgdonSounds fairly reasonable... Check with arianek to see what the current policy is about Drupal 5 docs though. I'm not sure. Generally, merging different version docs into one with small d6/7 specific sections is a good idea, but I'm just not sure what we're doing about d5 at this time.
Regarding page titles, shortening them might be OK, but keep in mind that the page titles are what the user will see in search results (google/drupal.org). So make sure the titles can stand alone (make sense out of context in a search result).
One last thought -- some of the pages are linked to from Drupal itself or from other pages, so just keep that in mind when merging them. Especially if a page has an alias, it will need a redirect.
Anyway, THANKS!! And please go ahead with at least the non-controversial things (like streamlining the content, reducing duplication, and rolling comments). When you find a page that isn't needed, go ahead and move it to the Archive book, and then comment here so we can figure out if it needs a redirect.
Comment #34
LarsKramer CreditAttribution: LarsKramer commentedHi jhodgdon, thanks for the quick feedback. I had not thought about those side effects of changing titles, so good you mentioned it. I'll keep that in mind.
Regarding Drupal 5 pages and content, I'll check with arianek before doing anything. My suggestions were based on Outdated/deprecated pages
I'll go ahead with the rest and post here as I advance.
Comment #35
LarsKramer CreditAttribution: LarsKramer commentedA few sidenotes about search results.
I just did some testing of what text turns up in Drupal's search results page when searching for "i18n" or "Internationalization", and limiting to Documentation.
In the first case I get:
And in the second:
In both cases not very useful I think. Do you know if there is any way (as docs editor) that I can influence what turns up later in the search results page? If you look at the results for the Drupal 5 and 6 versions of the 1i18n handbook, the first lines of the page content are shown, which I think makes more sense:
Comment #36
LarsKramer CreditAttribution: LarsKramer commentedMade the following updates:
The following pages are locked:
- Localizer: Build Multilingual Sites (Drupal 5 only)
- Translation Management - Systematic Process for Maintaining Translations
The first I think should be archived, and the second one moved one level up and have Drupal 7.x added to its version tags.
There are also some more pages about "Translation Manager" at http://drupal.org/node/1062032, which seem to be about the same module, so they should be merged, but these pages are locked too (I guess because of the images).
Comment #37
pixeliteI've cleaned up http://drupal.org/node/1113374 and http://drupal.org/node/1216132 somewhat. I would like to fix the Feature Overview page to move the Multilingual Taxonomy section to the dedicated taxonomy page: http://drupal.org/node/1114016 but that page is locked.
I can also add a page about setting up language detection, should this go under 'Translating a site interface to different languages (Locale core module)' or under the Tutorials section?
I hope to work on this issue more next week at the Montreal Code Sprint: http://groups.drupal.org/node/158434
Comment #38
jhodgdonThanks!
The page http://drupal.org/node/1114016 is locked because it has images embedded... I really hope someone will take on this issue: #528682: Allow inline images to be posted to Drupal.org project pages, docs pages, and comments without any special permissions sometime soon and fix that so we don't have to do that any more! Meanwhile, you can apply for doc admin privs if you want to edit that page:
http://drupal.org/node/472344
Sorry about the hassel!
Comment #39
sylvain_a CreditAttribution: sylvain_a commentedI'd like to let you know that i'm planning to dedicate some time to this next week, continuing the work that was done this spring, and taking into account the work that LarsKramer has done in the last month.
I also plan to be participating to the same Montreal Code Sprint next week.
Comment #40
jhodgdonSounds good. If at least one of you could make sure you have docs admin privs so you can edit pages with images, I am sure that would be helpful.
Comment #41
LarsKramer CreditAttribution: LarsKramer commentedI expect to get some time too next week to continue with this task.
When updating existing pages inside the i18n section, I think it would be good that we consider also incorporating D6 info if there is not too many differences between the two versions, so that in the end we can get remove the duplicated information inside the Internationalization 6.x section.
Regarding the page HowTo: Different home page, another approach is to use Views. Information about this approach might be included as a link to a separate HowTo (outside of i18n), or included in the same page, but then maybe it would better to have only one general HowTo section, outside the i18n section?
Comment #42
sylvain_a CreditAttribution: sylvain_a commentedI do have the docs admin privileges to edit that page, as well as the other pages with images. The more, the merrier!
Comment #43
pixeliteAt the sprint, we're planning on adding pages for the sub-modules the i18n package. At some point, we will probably group these into a new level of the book, since there are 14 sub-modules.
If time permits, we will also start adding documentation for the entity translation module, since none seems to exist a this point. At the moment, the best place for this seems to be under 'Contributed modules for language and locale'.
Comment #44
sylvain_a CreditAttribution: sylvain_a commentedHere is an update of tasks to be done in the upcoming hours.
Updating the submodules of i18n: http://drupal.org/node/133977
The basic idea would be to create a "Submodules of i18n page", and then list every submodule one level below.
Some pages are already existing one level up. Here are the details:
*Menus and primary / secondary links
- to be improved
- user case to be tested
- incomplete
*Multilingual Taxonomy
merge the section from overview
*And then we would need to create the following pages
- block translation
- field translation
- Multilingual select
- path translation
- string translation
- synchronize
- Multilingual content
- multilingual forum
- contact translation
- translation redirect
- translation sets
other tasks includes:
Some modules by themselves (outside of i18n) should be better documented.
For example:
- Entity Translation on same level as i18n
Notes: as information is available in the "help" section of the modules,
the handbook part could focus on setup and usercases.
Comment #45
sylvain_a CreditAttribution: sylvain_a commentedAdding a tag for the duration of the sprint, marking this as the main issue to read for the Multilingual Sprint in Montreal.
We'll be marking the tasks for the previous post in sub-issues, so you can refer to it by clicking on the tag.
Comment #46
sylvain_a CreditAttribution: sylvain_a commentedI don't think it's a good idea to merge the D6 and D7, as the modules are quite different in structure. It makes more sense to browse either a D6 guide, or a D7 guide, especially for i18n, which has a lot of submodules.
Comment #47
pixeliteI agree that merging the D6 and D7 sections would be confusing. Although the Multilingual Taxonomy page for D7 is similar to that for D6, once it's been updated, I think there will be enough differences to warrant maintaining separate pages for each version.
I do think it would make sense to move the D6 i18n section to the same level as the D7 section, instead of leaving it as a sub-section.
Comment #48
Gábor HojtsyCan you keep us updated on which ones you worked on?
Comment #49
sylvain_a CreditAttribution: sylvain_a commentedHere is the list:
http://drupal.org/project/issues/search/documentation?issue_tags=D8MI
Comment #50
pixeliteShould this i18n tutorial (http://drupal.org/node/1268692) be moved to the Internationalization section under
Building multilingual sites with the Internationalization (i18n) module > HowTos, tutorials and links
It seems out-of-place right now.
Comment #51
sylvain_a CreditAttribution: sylvain_a commentedI agree. Its parent page is actually a page we were trying to merge, following the discussion here:
http://drupal.org/node/1114504
Therefore, I moved the tutorial (http://drupal.org/node/1268692) under "HowTos, tutorials and links": http://drupal.org/node/1216118
Comment #52
sylvain_a CreditAttribution: sylvain_a commentedI'm currently trying to merge as much as possible from this page (http://drupal.org/node/254214) into the Working with Languages with handbook.
While this page was a good idea at the start, it is now confusing, since it provides multiple entry points to add tutorials. Therefore, following a discusssion, i've reduced the scope of the page and moved underlying tutorials.
For more details on the original issue:
http://drupal.org/comment/reply/1114504#comment-6
Comment #53
sylvain_a CreditAttribution: sylvain_a commentedI'm done merging content from "Translation, multilanguage content, and internationalization" (http://drupal.org/node/254214).
(based on this discussion : http://drupal.org/node/1114504).
Here's an update for my fellow sprinters:
- Updated title to reduce the scope of the page, and moved some of its subpages to the Working with Languages handbook. I agree "Other internationalization issues (other than translation)" might not be the optimal title, so i'm open to suggestions.
- Moved the i18n tutorial underneath this page to HowTos, tutorials and links (http://drupal.org/node/1216118) and modified the weight to make it come out first.
- Moved the Translation manager quick guide to "Complementary Modules for Multilingual Sites (Drupal 6)" (http://drupal.org/node/1114460)
- Renamed to "Importing data into multiple language", so it doesn't get confused as a i18n tutorial.
Marking it as "need review", so that someone can mark it as "fixed".
Comment #54
sylvain_a CreditAttribution: sylvain_a commentedAfter all this merging and discussing options, here is my proposal for the outline of the handbook
Working with languages
Comment #55
sylvain_a CreditAttribution: sylvain_a commentedLess than half a day left at the sprint. My plan is to review the new content entered (on documenting entity translation and i18n submodules).
Here is a quick recap.
- The priority was missing documentation.
This includes
- Then time was spent on cleaning up the handbook and merging duplicated "trunks" and starting point. Some pages were moved, and we're looking for some buy in from the authors.
Currently, the handbook is buried at the end of the structure guide. The aim of this clean up, completion and reorganizing is to make the handbook a candidate for a first level book, besides theming guide, administration guide, etc. The response is positive up to here.
http://drupal.org/documentation
If people want to help, they should review the new content, and test the workflow on a local site. More images would be needed for the book, but be aware that Docs Admin permissions is needed to edit pages with images.
Reference: http://drupal.org/project/issues/search/documentation?issue_tags=D8MI
Comment #56
sylvain_a CreditAttribution: sylvain_a commentedI'm wrapping up on the Documentation part of the sprint.
- There is now ongoing documentation on Entity Translation
- There is also new documentation about the features (submodules) of i18n.
- As an outcome, the "Working with Languages" handbook is now first level in drupal.org/documentation
http://drupal.org/node/1249130
Thank you to pixelite, salif and epoitras for contributing, and webchick for bringing the handbook issue to its conclusion. Of course, thanks to Gabor and the organizers for bringing every one in the same room.
@pixelite: epoitras has kindly accepted to make several screenshots for the submodules part of i18n, as he was granted the Docs Admin rights. I'm inviting you to follow up with him for the conclusion of this part of the guide.
Comment #57
pixeliteIt's confusing that the instructions for installing a language for Drupal 7 are in the Installation Guide http://drupal.org/localize.
But for Drupal 5/6, they're in the Locale section of the Multilingual Guide: http://drupal.org/node/21145.
I think the information should be linked to from both places, but it's confusing that these pages don't live in the same guide.
Comment #58
sylvain_a CreditAttribution: sylvain_a commentedTough call. Should this guide be in Installation, or under Multilingual?
If this falls under Multilingual, it could be the first item in the hierarchy.
Gabor, got an opinion on this?
Comment #59
sylvain_a CreditAttribution: sylvain_a commentedSince this is now a first level handbook, this qualifies for a review!
Comment #60
Gábor HojtsyCan we put it in multilingual and cross-reference from installation?
Comment #61
jhodgdonThat sounds reasonable to me. Do you have an opinion arianek?
Comment #62
sylvain_a CreditAttribution: sylvain_a commentedThis is from the Multilingual sprint in september 2011. Marking as fixed!