API localization discussion

Hello

Few days ago I've completed localized version of api.drupal.org site. It's the placed at the official russian community site at api.drupal.ru.
The site is on alpha-stage now, so any work on actual translation isn't made yet. But you can see examples of translation on the front page and in the Menu section of the Drupal6 documentation.

This site is based on API module version 5x-1x.

Localization made by the standard locale module. I've made corresponding changes to module to make possible per-paragraph based translation. It allows to ease translation very much, because there are many duplicate phrases on the documentation, such as Implementation of hook_user(). And also summaries in the list are too often equals complete description of a function/variable. With my approach, these phrases are translation only once and translation appears everywhere.

(If you want to try the site's translation abilities, log in with test:test)

I've attached the patch that allows doing all of these things.

But of course, there are several cave-eats that I found during this work.

First of all, files. For example, "Form Api reference". It contains huge variety of non-standard things (in the rest of documentation are only paragraphs and headers), that is difficult to translate by locale-module-way. It just throws away huge strings. So, now, I've just disabled translation of files now. But for future, I think that it can be done only using nodes. These thoughts bring me to the API module support queue and I found many requests from people who want the API reference as nodes.

I've read much about the subject and understand that there are several main bad-ass problems with this request:

1. Main requirement of API sites is ability to reindex source code again and again. So, if documentation will be in nodes, they must be recreated in some way without losing nodes' IDs (because people's bookmarks will link to IDs, not to paths).
2. Now, switching between API branches made by menu's primary tasks. I'm not big guru in Drupal6 menu system, but I expect that current realization of primary tasks will not work on node pages, because node itself has primary tasks (View, Edit, ...). It's very hazed part for me, so I'm skipping.
3. Ability to generate API nodes from translated chunks. Benefits of dividing content to chunks I've already explained in the beginning.

At this point, I will end my speech, and want to hear your thoughts about all of this.