Starting docs translation to spanish

17 views
Skip to first unread message

Alan Etkin

unread,
Oct 21, 2017, 7:39:59 AM10/21/17
to cocos2d discuss
I would like contribute to a spanish version of the current online docs for cocos2d. Any thoughts, pointers or suggestions welcome. I could use some reference to documentation on the docstring syntax and in particular, directions on how to deal with the translation of links and some technical language.

Alan

Daniel Gillet

unread,
Oct 21, 2017, 9:08:16 AM10/21/17
to cocos-...@googlegroups.com
Hello Alan,

Claudio is cocos2d maintainer. I've done a quick search and it seems that supporting multi-language documentation requires a bit of work as described here: http://www.sphinx-doc.org/en/stable/intl.html

I don't know how Claudio feels about this.

Daniel

On Sat, Oct 21, 2017 at 1:39 PM, Alan Etkin <spam...@gmail.com> wrote:
I would like contribute to a spanish version of the current online docs for cocos2d. Any thoughts, pointers or suggestions welcome. I could use some reference to documentation on the docstring syntax and in particular, directions on how to deal with the translation of links and some technical language.

Alan

--
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 cocos-discuss+unsubscribe@googlegroups.com.
To post to this group, send email to cocos-...@googlegroups.com.
Visit this group at https://groups.google.com/group/cocos-discuss.
For more options, visit https://groups.google.com/d/optout.

claudio canepa

unread,
Oct 21, 2017, 10:40:17 AM10/21/17
to cocos2d discuss
- 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.

- the programing guide, generated from .rst in the repo, should be easier to tackle

- 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.

- .py in master must not be bloated with translations

- 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)

- 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.

- 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



On Sat, Oct 21, 2017 at 8:39 AM, Alan Etkin <spam...@gmail.com> wrote:
I would like contribute to a spanish version of the current online docs for cocos2d. Any thoughts, pointers or suggestions welcome. I could use some reference to documentation on the docstring syntax and in particular, directions on how to deal with the translation of links and some technical language.

Alan

--

Alan Etkin

unread,
Oct 21, 2017, 12:29:13 PM10/21/17
to cocos-...@googlegroups.com
2017-10-21 11:40 GMT-03:00 claudio canepa <ccan...@gmail.com>:
- 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.
 
- 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.
 
- .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

claudio canepa

unread,
Oct 21, 2017, 4:41:59 PM10/21/17
to cocos2d discuss
On Sat, Oct 21, 2017 at 1:29 PM, Alan Etkin <spam...@gmail.com> wrote:


2017-10-21 11:40 GMT-03:00 claudio canepa <ccan...@gmail.com>:
- 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

--

Alan Etkin

unread,
Oct 21, 2017, 5:09:04 PM10/21/17
to cocos-...@googlegroups.com

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


Yes, that was more or less what I was thinking on. I think I was confusing when I talked mistakenly about "docstring syntax" in my first message. I meant I needed help with the tools used for creating the cocos2d docs.
 
 
 
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.

How much text per rebuild? Is it ok to translate a whole file before rebuilding?


claudio canepa

unread,
Oct 21, 2017, 7:28:05 PM10/21/17
to cocos2d discuss


On Sat, Oct 21, 2017 at 6:09 PM, Alan Etkin <spam...@gmail.com> wrote:

How much text per rebuild? Is it ok to translate a whole file before rebuilding?


The goal is to have few errors in each build; try a file, if too much errors revert half the edition and build again ?

--

Alan Etkin

unread,
Oct 23, 2017, 7:51:09 PM10/23/17
to cocos2d discuss


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.


I have already forked cocos2d, made a doc_es branch and cloned a local copy. Can I make test builds at the cloned folder or should I use a copy somewhere else? Not sure if the project ignores the builds.

claudio canepa

unread,
Oct 23, 2017, 10:25:49 PM10/23/17
to cocos2d discuss


On Mon, Oct 23, 2017 at 8:51 PM, Alan Etkin <spam...@gmail.com> wrote:


I have already forked cocos2d, made a doc_es branch and cloned a local copy. Can I make test builds at the cloned folder or should I use a copy somewhere else? Not sure if the project ignores the builds.


You can build in the repo clone, just be careful when doing a commit to not add generated files, that is, git status should only show
 - modified files for the ones edited
 - not tracked for all generated ones.


 

Daniel Gillet

unread,
Oct 24, 2017, 7:17:51 AM10/24/17
to cocos-...@googlegroups.com
Hello Alan,

+1 for what Claudio said. You will notice in the repository a file called .gitignore. It lists all the folder and files that git should not track. In there you can find a build/ directory which is where you will find your documentation build. So git will ignore all its content and you will not even see it if you do a git status.

I hope this helps,
Dan
Reply all
Reply to author
Forward
0 new messages