Let's consider this decoupled from Sphinx, for a minute: How do you handle translations in autodoc? Is there a standard way? Is not, what would be the best way?
I've looked (just quickly) to see if there is anything similar for other doc systems, and don't see anyone doing this. On Thu, Nov 20, 2008 at 9:55 AM, Christophe de VIENNE <[EMAIL PROTECTED]>wrote: > > I agree for simple rst files. What I don't see is how you would handle > autodoc content ? > > 2008/11/20 Yarko Tymciurak <[EMAIL PROTECTED]>: > > Oh! I thought docstrings to set the language / encoding of the file > > (self-document), with the directories just containing fully translated > > sources - entire copies of the work. > > That seems simple, and ultimately sufficient. It's not a dynamic web > site, > > where one must inject a translated messages in otherwise unknown content. > > With Sphinx, the content in total I expect to be translated. Why lookup? > > (e.g. gettext style)? Why "include other translated file"? Why not > just > > process a file(s) which is(are) the translation? > > Maybe that is the first question. > > Simpler is better. > > And if this is sufficient, then a makefile should be able to handle most > (if > > not all) of this, including common area for media and styling. Really, > I > > think all that is needed is to separate the content files. > > What do you think? > > Regards, > > Yarko > > On Thu, Nov 20, 2008 at 8:23 AM, Christophe de VIENNE < > [EMAIL PROTECTED]> > > wrote: > >> > >> I guess it is true if there is only 2, may be 3 languages to maintain. > >> For more languages it can become really painfull. I can't image > >> maintaining docstrings with 10 languages ! > >> > >> In this later case (a lot of translations), the gettext solution looks > >> more adequate. > >> > >> Any other though on this subject anybody ? > >> > >> Christophe > >> > >> 2008/11/20 Yarko Tymciurak <[EMAIL PROTECTED]>: > >> > ... which makes your first request (simple directive to select > >> > directory) > >> > seem like the simplest and perhaps correct solution for Sphinx > >> > Documents... > >> > > >> > On Thu, Nov 20, 2008 at 8:04 AM, Christophe de VIENNE > >> > <[EMAIL PROTECTED]> > >> > wrote: > >> >> > >> >> This way would look a lot like gettext integration. > >> >> > >> >> Sphinx would submit any paragraph or title it meets to gettext, and > we > >> >> would "only" have to write an adequate extractor, probably a new > >> >> sphinx builder. > >> >> > >> >> This way there would be no need to modify any extension, and the > >> >> "translate" directive would become almost unnecessary. > >> >> > >> >> That said, I do not know how painfull it would be to translate big > >> >> portions of text with gettext (I mean compared to short strings). > >> >> > >> >> thinking too... > >> >> > >> >> 2008/11/20 Yarko Tymciurak <[EMAIL PROTECTED]>: > >> >> > ...still thinking out loud, I think it would be easier to give > >> >> > someone a > >> >> > file to translate (perhaps?) if the idiom followed something along > >> >> > these > >> >> > lines: > >> >> > .. translate:: "some string" > >> >> > and > >> >> > .. translate:: %lang%/chapter1.rst > >> >> > > >> >> > for translated rst files > >> >> > The advantage would be to have one place where %lang%_strings.rst, > >> >> > and > >> >> > the > >> >> > various other files (e.g. chapter1.rst) existed. Simultaneous > >> >> > translation > >> >> > efforts of a work (at least) would not need to be merged then. > >> >> > I think the only work would be (in the second case) to do %lang% > >> >> > substitution before a simple include directive, and a Python > >> >> > dictionary > >> >> > lookup on a file named by convention in the first case. > >> >> > I wonder how terrible the lookups could get, and (to keep > consistent > >> >> > w/ > >> >> > behavior of other directives) how to manage paragraph translations, > >> >> > such > >> >> > as: > >> >> > .. translate:: > >> >> > * a list > >> >> > * of items > >> >> > ... still thinking... > >> >> > On Thu, Nov 20, 2008 at 5:25 AM, Christophe de VIENNE > >> >> > <[EMAIL PROTECTED]> > >> >> > wrote: > >> >> >> > >> >> >> Hi, > >> >> >> > >> >> >> 2008/11/17 Yarko Tymciurak <[EMAIL PROTECTED]>: > >> >> >> > I am thinking out loud here: > >> >> >> > This is an interesting question. > >> >> >> > I can imagine for some types of text (i.e. instructions) it > would > >> >> >> > be > >> >> >> > easier > >> >> >> > to keep consistent is the various language versions were in the > >> >> >> > same > >> >> >> > file, > >> >> >> > output by selector (so the .rst files themselves become > >> >> >> > self-contained > >> >> >> > translation files), and for other situations (where concepts are > >> >> >> > more > >> >> >> > important) that context be coherently developed in one language. > >> >> >> > I > >> >> >> > wonder > >> >> >> > if having the former structure (language conditional selector) > >> >> >> > could > >> >> >> > be > >> >> >> > the > >> >> >> > useful base - and larger context sections be included from > files, > >> >> >> > e.g. > >> >> >> > something that looks like: > >> >> >> > -------------------------------- > >> >> >> > .. lang:: en > >> >> >> > Contents > >> >> >> > .. lang:: fr > >> >> >> > Contenu > >> >> >> > .. lang:: it > >> >> >> > Soddisfare > >> >> >> > > >> >> >> > .. include:: chapter1.%lang%.rst > >> >> >> > or perhaps > >> >> >> > .. include:: %lang$/chapter1.rst > >> >> >> > ------------------------------------ > >> >> >> > The form I've written might be wrong - I mainly want to get the > >> >> >> > concept > >> >> >> > accross .... at the top of the file, or at build time, some > >> >> >> > language > >> >> >> > (or > >> >> >> > lang) setting would be made... > >> >> >> > >> >> >> Ideally we would have a "languages" variable in conf.py, along > with > >> >> >> a > >> >> >> default_language. > >> >> >> If such options are used, the builders would be run one time for > >> >> >> each > >> >> >> language and the language code appended to the output directory > >> >> >> name. > >> >> >> > >> >> >> > I wonder if this wouldn't be useful and flexible idiom for > >> >> >> > authors? > >> >> >> > >> >> >> It think it looks great. That would be perfect for my needs > >> >> >> > >> >> >> > Reasonable to implement? > >> >> >> > >> >> >> I have no idea. If it is, I would be happy to give a hand. > >> >> >> > >> >> >> > Regards, > >> >> >> > Yarko > >> >> >> > > >> >> >> > > >> >> >> > On Mon, Nov 17, 2008 at 5:27 AM, Christophe de VIENNE > >> >> >> > <[EMAIL PROTECTED]> > >> >> >> > wrote: > >> >> >> >> > >> >> >> >> Hi, > >> >> >> >> > >> >> >> >> I will need to maintain my documentation in french and in > >> >> >> >> english. I > >> >> >> >> would like to know if some of you do such a thing, and how to > you > >> >> >> >> proceed ? > >> >> >> >> My idea is to have two different roots, en and fr which are > >> >> >> >> totally > >> >> >> >> independent. I wonder if there is anything in sphinx to make > this > >> >> >> >> easier. > >> >> >> >> > >> >> >> >> Especially for the autodoc extension : It would be great if I > >> >> >> >> could > >> >> >> >> have both versions as docstrings with a directive to tell > sphinx > >> >> >> >> the > >> >> >> >> language of the text. > >> >> >> >> > >> >> >> >> Thanks for any hint on this issue, > >> >> >> >> > >> >> >> >> Christophe > >> >> >> >> > >> >> >> >> > >> >> >> > > >> >> >> > > >> >> >> > > > >> >> >> > > >> >> >> > >> >> >> > >> >> > > >> >> > > >> >> > > > >> >> > > >> >> > >> >> > >> > > >> > > >> > > > >> > > >> > >> > > > > > > > > > > > > > --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "sphinx-dev" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/sphinx-dev?hl=en -~----------~----~----~----~------~----~------~--~---
