Hi Mickaël,
>
> I prefer the second solution because when an user read a translated
> documentation, he can understand that some parts are not translated but he
> want an complete and *up-to-date* documentation.
I agree, I think we should add some prefix text in the document that are
not translated and still in English, something like [ENG] followed by
the title. With that change we can easily check for docs to be translated.
>
> Even if the translation can be a difficult work, maintain a translation is
> certainly the most difficult part of the work. Then we adopted some rules
> to simplify the work of maintainers:
> 1) Remove the (manual.xml | index.rst) in each language => this limits the
> forgetting of a line when adding a file in the main documentation
The index.rst is in english and If we want to provide a full translation
we have to translate this file. That means we cannot remove it.
> 2) Put any translation outside the (manual.xml | index.rst) file => if we
> remove index.rst, we need to provide an alternative to translate title for
> example. We resolved it with XML entities with Docbook. The question is
> opened for reST
I think we can simplify that process using specific index.rst for each
language. The management, and the update, of this file is a
responsibility of the translator.
> 3) Allow translators to easily detect modifications in English files =>
> with ZF1, I created a translator tool (
http://mikaelkael.dyndns.org/checker/)
> that can detect them with the help of a specific tag (exactly the same as
> PHP documentation). With Docbook and SVN it's a comment tag with the
> English revision number on which the translated file is based: "<!--
> EN-Revision: 25000 -->". With reST and Git, it can be something like: "..
> EN-Revision: 9a21dca" at the top/bottom of the file. Of course, with this,
> I will update the translator tool.
I think this is a very good tool and we should update it to work on reST
and Git.
This is an open question. I didn't use the internationalization solution
used by Sphinx because I think is not so good for a community project
like Zend Framework 2. I tried to translate the English docs in another
language using the .pot, .po and .mo files but at the end I had a couple
of giant files with all the sentences spread.
I think this is not so good to facilitate the work of translators. I
think is better to manage .rst file for each language.
That means right now we can use readthedocs.org only for the English
documentation. The only solution that I see right now is to create
different project in readthedocs.org for different languages and use
some "hack" to execute the Makefile for the specific language.
Regards,
Enrico Zimuel
>
>
> 2012/8/6 Enrico Zimuel <
[hidden email]>
>
>> Hi Mickael,
>>
>> I see the problem for the translation of zf2-documentation.
>> Right now we don't have all the files translated and if you try to
>> compile the docs you will get errors (missing files).
>>
>> I see two ways to manage this issue:
>>
>> 1) change the index.rst file (Table Of Contents) for each languages to
>> include only the translated files;
>>
>> 2) modify the Makefile to be able to copy the missing files from
>> /docs/languages/en and copy to the local languages throwing a message to
>> the user that say something like "The xxx file is missing from the
>> translation, I used the english file as temporary file"
>>
>> I just discovered that you are already working on the second solution :)
>>
>>
https://github.com/mikaelkael/zf2-documentation/commit/9a21dca53966b03e8e32f666c601b8a21298ac06>>
>> That's great!
>> I think we can work on the second solution.
>> Folks any other ideas on that?
>>
>> Regards,
>> Enrico Zimuel
>>
>> On 08/06/2012 09:46 AM, Mickael Perraud wrote:
>>> Hi all,
>>>
>>> Is it allowed to begin translation? It seems not for the moment =>
>>>
https://github.com/zendframework/zf2-documentation/pull/119>>>
>>> I really don't understand comment like: "I know there is a bug, I know
>> that
>>> you correct it, I simply don't want to apply your PR".
>>>
>>> Can you clarify this point, I don't want a battle each I will have a PR.
>>>
>>> Thanks in advance.
>>> --
>>> Mickaël Perraud
>>> Website |
http://mikaelkael.fr>>> Twitter |
http://twitter.com/mikaelkael>>> PGP key |
http://mikaelkael.fr/mikaelkael.asc>>>
>>>
>>>
>>> 2012/8/2 Enrico Zimuel <
[hidden email]>
>>>
>>>> Hi all,
>>>>
>>>> i just wrote this post on devzone.zend.com on how to contribute to the
>>>> ZF2 documentation project:
>>>>
>>>>
http://devzone.zend.com/2463/zf2-documentation-we-want-you/>>>>
>>>> In the post I put evidence on the contribution process and how to use
>>>> the "Edit this document" button in the zf2.readthedocs.org site.
>>>>
>>>> Help us to spread this post, thanks!
>>>>
>>>> --
>>>> Enrico Zimuel
>>>> Senior PHP Engineer |
[hidden email]
>>>> Zend Framework Team |
http://framework.zend.com>>>> Zend Technologies Ltd.
>>>>
http://www.zend.com>>>>
>>>
>>
>>
>> --
>> Enrico Zimuel
>> Senior PHP Engineer |
[hidden email]
>> Zend Framework Team |
http://framework.zend.com>> Zend Technologies Ltd.
>>
http://www.zend.com>>
>
--
Enrico Zimuel
Senior PHP Engineer |
[hidden email]
Zend Framework Team |
http://framework.zend.comZend Technologies Ltd.
http://www.zend.com
Locked
