[py-dev] pytest documents with Japanese translation

Tetsuya Morimoto tetsuya.morimoto at gmail.com
Thu Jun 7 02:09:46 CEST 2012 

Hi Holger, Ronny

In my opinion, I agree with Ronny's idea (use Sphinx i18n feature),
because of its maintainability.

However, we need to change some operations for documentation workflow
if we started to use Sphinx i18n feature. I don't know you want it or
not, in this time.

Though I haven't used Sphinx i18n feature, I'm willing to investigate
the functionality and make the documentation workflow if you want.

thanks,
Tetsuya

On Wed, Jun 6, 2012 at 9:35 PM, holger krekel <holger at merlinux.eu> wrote:
> Hello Ronny,
>
> On Wed, Jun 06, 2012 at 13:59 +0200, Ronny Pfannschmidt wrote:
>> Hi Holger, Tetsuya
>>
>> while taking a look i noticed that sphinx has a integrated
>> translation system based on .po files
>>
>> see http://sphinx.pocoo.org/latest/intl.html
>>
>> im under the impression that this way is more maintainable than he
>> current way due to using standard tools to manage translated strings
>>
>> i'd like to suggest some investigation in its usefullness
>
> I am happy to consider using it - not sure i get to try it myself
> any time soon and wonder specifically if a two-language situation with
> not so often changing docs warrants using the above system.
>
> Tetsuya, what do you think? Can you imagine investigating a bit?
>
> best,
> holger
>
>> -- ronny
>>
>>
>> On 06/06/2012 02:07 AM, Tetsuya Morimoto wrote:
>> >Hi Holger,
>> >
>> >I sent a pull request. Confirm it!
>> >
>> >https://bitbucket.org/hpk42/pytest/pull-request/14/added-japanese-translation-documentation
>> >
>> >thanks,
>> >Tetsuya
>> >
>> >On Sat, Jun 2, 2012 at 8:35 PM, holger krekel<holger at merlinux.eu>  wrote:
>> >>Hi Tetsuya,
>> >>
>> >>On Sat, Jun 02, 2012 at 20:15 +0900, Tetsuya Morimoto wrote:
>> >>>Hi Holger,
>> >>>
>> >>>I merged the changes of 2.2.4 into my translation repository. I mean
>> >>>it's available to send a pull request.
>> >>>https://bitbucket.org/t2y/pytest-ja
>> >>>
>> >>>I think it's better to send a pull request from me after you
>> >>>reorganize the docs directory in your repository. Maybe, I re-fork
>> >>>pytest repository to drop the named branch for translation, anyway, I
>> >>>will follow your way.
>> >>
>> >>Can you imagine to do the doc reorganisation yourself?  This way there
>> >>is no need for a named branch - you could just do the final sub
>> >>directory layout as discussed in the last mail.  I would care for the
>> >>"push-to-website" bit and the apache side reconfiguration.
>> >>
>> >>best,
>> >>holger
>> >>
>> >>
>> >>>thanks,
>> >>>Tetsuya
>> >>>
>> >>>On Wed, May 30, 2012 at 12:07 AM, Tetsuya Morimoto
>> >>><tetsuya.morimoto at gmail.com>  wrote:
>> >>>>Hi Holger,
>> >>>>
>> >>>>Thanks for remembering the translation! :)
>> >>>>
>> >>>>>Does this also make sense to you?  If so, it'd be great if you could
>> >>>>>submit a pull request that reorganises pytest's docs accordingly,
>> >>>>>preferably starting from the current trunk.
>> >>>>Yes, it makes sense for me. I have experienced a similar work for
>> >>>>virtualenvwrapper. That might be an informative.
>> >>>>
>> >>>>http://www.doughellmann.com/docs/virtualenvwrapper/index.html
>> >>>>http://www.doughellmann.com/docs/virtualenvwrapper/ja/index.html
>> >>>>https://bitbucket.org/dhellmann/virtualenvwrapper/src/e1a05e751a56/docs
>> >>>>
>> >>>>>There weren't much changes
>> >>>>>between 2.2.3 and 2.2.4 in the doc directory, anyway.
>> >>>>OK! I will update the Japanese translation and submit a pull request!
>> >>>>
>> >>>>>I'll take care to push the docs to pytest.org - maybe using a scheme like this:
>> >>>>>
>> >>>>>    pytest.org/VER/... # for english documentation
>> >>>>>    pytest.org/en/VER  # for english documentation
>> >>>>>    pytest.org/ja/VER  # for japanese documentation
>> >>>>>
>> >>>>>where VER is a version number and "latest" could point to the latest number.
>> >>>>It looks nice. I agree with you.
>> >>>>
>> >>>>>that there is another error i am not sure about at the moment.
>> >>>>>Maybe Ronny can take a look.
>> >>>>I see. I will talk to Ronny later.
>> >>>>
>> >>>>thanks,
>> >>>>Tetsuya
>> >>>>
>> >>>>On Tue, May 29, 2012 at 11:13 PM, holger krekel<holger at merlinux.eu>  wrote:
>> >>>>>Hi Tetsuya,
>> >>>>>
>> >>>>>On Mon, Apr 23, 2012 at 03:43 +0900, Tetsuya Morimoto wrote:
>> >>>>>>Hi Holger,
>> >>>>>>
>> >>>>>>Thanks for thinking about Japanese translation.
>> >>>>>
>> >>>>>sorry for taking a while.
>> >>>>>
>> >>>>>>>* how do the eventual URLs look like? Maybe pytest.org/latest-jp/...?
>> >>>>>>>  instead of pytest.org/latest/ ?
>> >>>>>>>  I'd definitely like to keep existing URLs working.
>> >>>>>>It's good idea and I suggest "latest-ja" is proper than "latest-jp"
>> >>>>>>since "jp" is the country code.
>> >>>>>
>> >>>>>I think the eventual URL is not a big problem.  We just need to take
>> >>>>>care that it is compatible with the existing scheme, i.e. allows existing
>> >>>>>URLs to remain valid.
>> >>>>>
>> >>>>>>>* how to organise the repository so that both EN and JP are included
>> >>>>>>>  (without the need to have a branch)
>> >>>>>>I forked original branch for Japanese translation and made named
>> >>>>>>branch to represent the version, but do you want to manage the
>> >>>>>>translation in original repository? If so, I know Sphinx has i18n
>> >>>>>>feature using gettext since 1.1. Is this useful for your purpose?
>> >>>>>>http://sphinx.pocoo.org/latest/intl.html
>> >>>>>
>> >>>>>I think what we need is something along those lines:
>> >>>>>
>> >>>>>http://mark-story.com/posts/view/creating-multi-language-documentation-with-sphinx
>> >>>>>
>> >>>>>Does this also make sense to you?  If so, it'd be great if you could
>> >>>>>submit a pull request that reorganises pytest's docs accordingly,
>> >>>>>preferably starting from the current trunk.  There weren't much changes
>> >>>>>between 2.2.3 and 2.2.4 in the doc directory, anyway.
>> >>>>>
>> >>>>>I think we'd end up with something like:
>> >>>>>
>> >>>>>    pytest/
>> >>>>>        doc/
>> >>>>>            en/
>> >>>>>                # current english files and dirs
>> >>>>>            ja/
>> >>>>>                # current japanese files and dirs
>> >>>>>
>> >>>>>I'll take care to push the docs to pytest.org - maybe using a scheme like this:
>> >>>>>
>> >>>>>    pytest.org/VER/... # for english documentation
>> >>>>>    pytest.org/en/VER  # for english documentation
>> >>>>>    pytest.org/ja/VER  # for japanese documentation
>> >>>>>
>> >>>>>where VER is a version number and "latest" could point to the latest number.
>> >>>>>
>> >>>>>>>* do we need to do anything special wrt to the examples and their
>> >>>>>>>  generation? (we use a tool called 'regendoc' written by ronny which
>> >>>>>>>  regenerates the example outputs)
>> >>>>>>I used original example code with document, so the example's version
>> >>>>>>are "pytest-2.2.2"? And then, I tried to run regen (make regen), but I
>> >>>>>>got an error. It seems regenerating has an encoding issue.
>> >>>>>>
>> >>>>>>(sphinx)$ make regen
>> >>>>>>PYTHONDONTWRITEBYTECODE=1 COLUMNS=76 regendoc --update *.txt */*.txt
>> >>>>>>===== checking apiref.txt =====
>> >>>>>>Traceback (most recent call last):
>> >>>>>>   File "/Users/t2y/.virtualenvs/sphinx/bin/regendoc", line 9, in<module>
>> >>>>>>     load_entry_point('RegenDoc==0.2.dev1', 'console_scripts', 'regendoc')()
>> >>>>>>   File "/Users/t2y/work/python/regendoc/regendoc.py", line 201, in main
>> >>>>>>     return _main(options.files, should_update=options.update)
>> >>>>>>   File "/Users/t2y/work/python/regendoc/regendoc.py", line 196, in _main
>> >>>>>>     path.write(corrected)
>> >>>>>>   File "/Users/t2y/.virtualenvs/sphinx/lib/python2.7/site-packages/py/_path/local.py",
>> >>>>>>line 385, in write
>> >>>>>>     data = py.builtin._totext(data, sys.getdefaultencoding())
>> >>>>>>UnicodeDecodeError: 'ascii' codec can't decode byte 0xe3 in position
>> >>>>>>22: ordinal not in range(128)
>> >>>>>>make: *** [regen] Error 1
>> >>>>>
>> >>>>>One problem is that regendoc.py:196 should call "path.write(corrected,
>> >>>>>'wb')" in order to write out bytes and inhibit conversions. But after
>> >>>>>that there is another error i am not sure about at the moment.
>> >>>>>Maybe Ronny can take a look.
>> >>>>>
>> >>>>>best,
>> >>>>>holger
>> >>>>>
>> >>>>>>thanks,
>> >>>>>>Tetsuya
>> >>>>>>
>> >>>>>>On Fri, Apr 20, 2012 at 12:45 PM, holger krekel<holger at merlinux.eu>  wrote:
>> >>>>>>>Hi Tetsuya,
>> >>>>>>>
>> >>>>>>>thanks for your work already!
>> >>>>>>>
>> >>>>>>>i guess we need to work a bit to have both language versions
>> >>>>>>>generated.  I haven't looked at your branch yet but i guess
>> >>>>>>>we need to solve a few issues:
>> >>>>>>>
>> >>>>>>>* how do the eventual URLs look like? Maybe pytest.org/latest-jp/...?
>> >>>>>>>  instead of pytest.org/latest/ ?
>> >>>>>>>  I'd definitely like to keep existing URLs working.
>> >>>>>>>
>> >>>>>>>* how to organise the repository so that both EN and JP are included
>> >>>>>>>  (without the need to have a branch)
>> >>>>>>>
>> >>>>>>>* do we need to do anything special wrt to the examples and their
>> >>>>>>>  generation? (we use a tool called 'regendoc' written by ronny which
>> >>>>>>>  regenerates the example outputs)
>> >>>>>>>
>> >>>>>>>best,
>> >>>>>>>holger
>> >>>>>>>
>> >>>>>>>
>> >>>>>>>On Mon, Apr 16, 2012 at 16:24 +0900, Tetsuya Morimoto wrote:
>> >>>>>>>>Hi,
>> >>>>>>>>
>> >>>>>>>>I finished translating pytest documents English to Japanese. My
>> >>>>>>>>repository is below and I made the named branch "2.2.3-ja" for
>> >>>>>>>>translating docs.
>> >>>>>>>>
>> >>>>>>>>https://bitbucket.org/t2y/pytest-ja
>> >>>>>>>>
>> >>>>>>>>I would like to publish this Japanese translation on pytest.org with
>> >>>>>>>>some ways. But, I don't know it's possible or not, and how to deploy
>> >>>>>>>>the current docs. I think putting original and translated docs
>> >>>>>>>>separately is easy deployment to avoid some conflicts. Of course,
>> >>>>>>>>other suggestions are welcome.
>> >>>>>>>>
>> >>>>>>>>Additionally, I can maintain Japanese docs in the future. So, I can
>> >>>>>>>>work by myself if you give me needed permission.
>> >>>>>>>>
>> >>>>>>>>thanks,
>> >>>>>>>>Tetsuya
>> >>>>>>>>_______________________________________________
>> >>>>>>>>py-dev mailing list
>> >>>>>>>>py-dev at codespeak.net
>> >>>>>>>>http://codespeak.net/mailman/listinfo/py-dev
>> >>>>>>>>
>> >>>>>>_______________________________________________
>> >>>>>>py-dev mailing list
>> >>>>>>py-dev at codespeak.net
>> >>>>>>http://codespeak.net/mailman/listinfo/py-dev
>> >>>
>> >_______________________________________________
>> >py-dev mailing list
>> >py-dev at codespeak.net
>> >http://codespeak.net/mailman/listinfo/py-dev
>>

More information about the Pytest-dev mailing list