On Sat, Oct 21, 2017 at 1:29 PM, Alan Etkin <[email protected]> wrote:
> > > 2017-10-21 11:40 GMT-03:00 claudio canepa <[email protected]>: > >> - core issue: what tooling and workflow could work, both to translation >> maintainer and cocos committers, not only as an one shoot translation but >> for maintenance. >> > > Actually I was thinking in a per-main release or similar static > translation. Even it could be posted as an external resource. No need to > modify the cocos doc service. However, I understand the profits of > community maintained multi-language automated translation. If that is the > preferred option, I will see how to contribute to it. > > >> >> - the programing guide, generated from .rst in the repo, should be easier >> to tackle >> >> > I was mainly interested in translating that part. I think the API would be > too much for a single amateur translator. > With a reduced scope things would be way easier. > > >> - the api reference is tougher: sphinx scans the .py docstrings and >> produces .rst in a first pass, to docgen/api, and then the second pass >> renders to final format (html). Needs alternative source for the >> docstrings, and hooking in the sphinx build system to orchestrate the data >> flow in each language. >> >> > I have no idea how to deal with it. I'm just a markmin average user :P. > Not impossible though it would take some time. > > Then I'd suggest to start with reduced scope and low tech. How about - you fork los-cocos/cocos in gitbub - create a branch doc_es , translate in that branch the files in docgen/programming_guide (meaning you edit the existing files, not copies; that will allow to build the docs without changing any code) - In that branch don't edit anything outside docgen/programming_guide This will let you start the translation now, and you are able to build the docs at any time. Look in tools/ subdir for the files building_release_notes.txt and release_checklist_template.txt , they have sections about how to build the docs. >From the software side you will need to pip install sphinx to be able to render, and have installed pyglet 1.2.4 (newer pyglet will break the build) In docgen/dev/documentation.txt they are some notes about the sphinx / reST markup that may help; other than that search sphinx / docutils documentation I would suggest to make a first build before editing anything and save the log and console output as reference; translations should not increase the count of warnings. Then you translate small sections and rebuild, if they are new warnings or errors fix that before continuing to translate. Also look if the relevant html page looks good. This should produce an usable translation without any technical complication. To handle updates a git diff over docgen/programming_guide in master, between (last revision translated) and (current master) should point which areas will need translation updates. If you are not particularly interested in doc building and translation toolchains, that's all. Otherwise, you can talk to people maintaining translations to get ideas and experiment. Overall, keep the scope aligned with your interests: it would no good to tackle a big scope of things that not really interest you. -- ccanepa > - .py in master must not be bloated with translations >> > > Of course > > >> >> - the english build must be a stock sphinx build (if other lang needs >> extra or custom extensions, and changes in sphinx broke that, I don't want >> docs to be showstopper for release) >> > > It seems that translating the api could be a real problem. > > >> >> - I have no experience with sphinx and translations, I would ping people >> from the pyar list (I think I have seen your mail there ?). Specifically >> Hugo Ruscitti, I think at some time he talked about supporting docstring >> translation for some project (Pilas ?), Humitos maybe, he is involved in >> translation projects. Others in that list had done docs translation, so >> maybe asking also in the list will suggest tooling and workflows. >> >> > I was part of pyar list but I dismissed. I will register again so I can > ask for help. > > >> - A look at the link provided by Daniel may be productive >> >> In a pinch, I think you should do a preliminary work like >> - by asking people, have an idea of how hard api docs translations can >> be >> - decide the translation scope: only programming guide or the full >> thing ? >> - propose a sketch of the tooling and workflow for discussion >> > > Ok, I will > > -- > You received this message because you are subscribed to the Google Groups > "cocos2d discuss" group. > To unsubscribe from this group and stop receiving emails from it, send an > email to [email protected]. > To post to this group, send email to [email protected]. > Visit this group at https://groups.google.com/group/cocos-discuss. > For more options, visit https://groups.google.com/d/optout. > -- You received this message because you are subscribed to the Google Groups "cocos2d discuss" group. To unsubscribe from this group and stop receiving emails from it, send an email to [email protected]. To post to this group, send email to [email protected]. Visit this group at https://groups.google.com/group/cocos-discuss. For more options, visit https://groups.google.com/d/optout.
