Multi language support for ZF2 docs

[Enrico Zimuel-2]

Hi all,

i just merged the new document tree for ZF2 to support the multi
languages: https://github.com/zendframework/zf2-documentation.

Now the tree dir is structured as follow:

docs
docs/Makefile
docs/languages/
docs/languages/en/
docs/languages/en/conf.py
docs/languages/en/index.rst
docs/languages/en/modules/
docs/languages/en/images/
docs/languages/en/ref/
docs/languages/en/tutorials/

In order to translate the documentation in another languages we have to
copy the entire en folder. I used this approach instead of use the
internazionalizatin feature of Sphinx because in this way we can manage
the documentation file by file in reStructuredText format
(http://sphinx.pocoo.org/latest/intl.html).

The multi language approach of Sphinx uses gettext to generate multiple
files .pot, .po and .mo in order to render a document in different
languages.
The .pot files are not so easy to manage because they collect all the
paragraphs of the entire documentation. Moreover each time we change
something in the en folder we have to re-build the .pot files.

I prefered to split the documentation in separate folders for each
language. In this way the versioning of the files is much more easy.

I changed the Makefile in order to manage the different languages using
the parameter LANG. To have more info on how to render the documentation
in different languages read this file:
https://github.com/zendframework/zf2-documentation/blob/master/CONTRIBUTE.md


--
Enrico Zimuel
Senior PHP Engineer     | [hidden email]
Zend Framework Team     | http://framework.zend.com
Zend Technologies Ltd.
http://www.zend.com

[Ben Scholzen 'DASPRiD']

Hi Enrico,

Since you didn't name it exactly, how is synchronization of
translations with the source language (english) done? Paragraphs in PO
files would simply show if something was updated.

Regards,
Ben

Am 19.07.2012 12:43, schrieb Enrico Zimuel:

> Hi all,
>
> i just merged the new document tree for ZF2 to support the multi
> languages: https://github.com/zendframework/zf2-documentation.
>
> Now the tree dir is structured as follow:
>
> docs
> docs/Makefile
> docs/languages/
> docs/languages/en/
> docs/languages/en/conf.py
> docs/languages/en/index.rst
> docs/languages/en/modules/
> docs/languages/en/images/
> docs/languages/en/ref/
> docs/languages/en/tutorials/
>
> In order to translate the documentation in another languages we have
> to
> copy the entire en folder. I used this approach instead of use the
> internazionalizatin feature of Sphinx because in this way we can
> manage
> the documentation file by file in reStructuredText format
> (http://sphinx.pocoo.org/latest/intl.html).
>
> The multi language approach of Sphinx uses gettext to generate
> multiple
> files .pot, .po and .mo in order to render a document in different
> languages.
> The .pot files are not so easy to manage because they collect all the
> paragraphs of the entire documentation. Moreover each time we change
> something in the en folder we have to re-build the .pot files.
>
> I prefered to split the documentation in separate folders for each
> language. In this way the versioning of the files is much more easy.
>
> I changed the Makefile in order to manage the different languages
> using
> the parameter LANG. To have more info on how to render the
> documentation
> in different languages read this file:
>
> https://github.com/zendframework/zf2-documentation/blob/master/CONTRIBUTE.md

[Enrico Zimuel-2]

Hi Ben,

with this approach to have multiple folders with .rst files for each
languages we don't have synchronization. Basically is the same solution
that we have right now using DocBook.

I followed this approach because the idea to use gettext and generate a
big .pot file that contains all the paragraphs is not so good. If more
that one people is working on the same language we will have a lot of
conflicts. Manage multiple files in a simple format like
reStructuredText is much more easy (even github support reStructuredText).

The synchronization can be done manually, I don't think this is a big
problem. Even because I hope we will finalize the English documents soon
so we can start to translate without a lot of changes.

Regards,
Enrico

On 07/19/2012 03:43 PM, Ben Scholzen wrote:

> Hi Enrico,
>
> Since you didn't name it exactly, how is synchronization of translations
> with the source language (english) done? Paragraphs in PO files would
> simply show if something was updated.
>
> Regards,
> Ben
>
> Am 19.07.2012 12:43, schrieb Enrico Zimuel:
>> Hi all,
>>
>> i just merged the new document tree for ZF2 to support the multi
>> languages: https://github.com/zendframework/zf2-documentation.
>>
>> Now the tree dir is structured as follow:
>>
>> docs
>> docs/Makefile
>> docs/languages/
>> docs/languages/en/
>> docs/languages/en/conf.py
>> docs/languages/en/index.rst
>> docs/languages/en/modules/
>> docs/languages/en/images/
>> docs/languages/en/ref/
>> docs/languages/en/tutorials/
>>
>> In order to translate the documentation in another languages we have to
>> copy the entire en folder. I used this approach instead of use the
>> internazionalizatin feature of Sphinx because in this way we can manage
>> the documentation file by file in reStructuredText format
>> (http://sphinx.pocoo.org/latest/intl.html).
>>
>> The multi language approach of Sphinx uses gettext to generate multiple
>> files .pot, .po and .mo in order to render a document in different
>> languages.
>> The .pot files are not so easy to manage because they collect all the
>> paragraphs of the entire documentation. Moreover each time we change
>> something in the en folder we have to re-build the .pot files.
>>
>> I prefered to split the documentation in separate folders for each
>> language. In this way the versioning of the files is much more easy.
>>
>> I changed the Makefile in order to manage the different languages using
>> the parameter LANG. To have more info on how to render the documentation
>> in different languages read this file:
>>
>> https://github.com/zendframework/zf2-documentation/blob/master/CONTRIBUTE.md
>>
>
>

--
Enrico Zimuel
Senior PHP Engineer     | [hidden email]
Zend Framework Team     | http://framework.zend.com
Zend Technologies Ltd.
http://www.zend.com

[demiankatz]

I've just written a blog post about how my ZF2 project-in-progress uses a custom module to allow core code to be shared between a web application and a set of command line tools:

http://blog.library.villanova.edu/libtech/2012/07/19/moving-vufind-to-zend-framework-2-part-4-command-line-tools/

I'm sharing this for three reasons:

1.) I thought it might be of interest to others facing the same problems.
2.) I'm hoping that someone with more Zend Framework 2 knowledge may have some comments on how I could do this better.
3.) Perhaps it can advance some of the conversations about the CLI RFC (http://framework.zend.com/wiki/display/ZFDEV2/RFC+-+CLI).

If nothing else, it demonstrates a few needs that aren't explicitly laid out in the current RFC:

1.) Sharing bootstrapping between web and CLI apps (possibly addressed by the final note in the document).
2.) The need for real-time feedback in addition to generation of a response object.
3.) The need for setting an exit status (presumably a necessary feature of the CLI response object).

I hope this is helpful, and I'll be happy to discuss it further if anyone is interested.

- Demian

[Enrico Zimuel-2]

Hi Ben,

with this approach to have multiple folders with .rst files for each
languages we don't have synchronization. Basically is the same solution
that we have right now using DocBook.

I followed this approach because the idea to use gettext and generate a
big .pot file that contains all the paragraphs is not so good. If more
that one people is working on the same language we will have a lot of
conflicts. Manage multiple files in a simple format like
reStructuredText is much more easy (even github support reStructuredText).

The synchronization can be done manually, I don't think this is a big
problem. Even because I hope we will finalize the English documents soon
so we can start to translate without a lot of changes.

Regards,
Enrico

On 07/19/2012 03:43 PM, Ben Scholzen wrote:

> Hi Enrico,
>
> Since you didn't name it exactly, how is synchronization of translations
> with the source language (english) done? Paragraphs in PO files would
> simply show if something was updated.
>
> Regards,
> Ben
>
> Am 19.07.2012 12:43, schrieb Enrico Zimuel:
>> Hi all,
>>
>> i just merged the new document tree for ZF2 to support the multi
>> languages: https://github.com/zendframework/zf2-documentation.
>>
>> Now the tree dir is structured as follow:
>>
>> docs
>> docs/Makefile
>> docs/languages/
>> docs/languages/en/
>> docs/languages/en/conf.py
>> docs/languages/en/index.rst
>> docs/languages/en/modules/
>> docs/languages/en/images/
>> docs/languages/en/ref/
>> docs/languages/en/tutorials/
>>
>> In order to translate the documentation in another languages we have to
>> copy the entire en folder. I used this approach instead of use the
>> internazionalizatin feature of Sphinx because in this way we can manage
>> the documentation file by file in reStructuredText format
>> (http://sphinx.pocoo.org/latest/intl.html).
>>
>> The multi language approach of Sphinx uses gettext to generate multiple
>> files .pot, .po and .mo in order to render a document in different
>> languages.
>> The .pot files are not so easy to manage because they collect all the
>> paragraphs of the entire documentation. Moreover each time we change
>> something in the en folder we have to re-build the .pot files.
>>
>> I prefered to split the documentation in separate folders for each
>> language. In this way the versioning of the files is much more easy.
>>
>> I changed the Makefile in order to manage the different languages using
>> the parameter LANG. To have more info on how to render the documentation
>> in different languages read this file:
>>
>> https://github.com/zendframework/zf2-documentation/blob/master/CONTRIBUTE.md
>>
>
>

--
Enrico Zimuel
Senior PHP Engineer     | [hidden email]
Zend Framework Team     | http://framework.zend.com
Zend Technologies Ltd.
http://www.zend.com

[David Muir-2]

Demian,

Could you resend this to the list as a new email so that it doesn't get
buried in the Mulit language support thread?

Cheers,
David

On 20/07/12 01:35, Demian Katz wrote:

> I've just written a blog post about how my ZF2 project-in-progress uses a custom module to allow core code to be shared between a web application and a set of command line tools:
>
> http://blog.library.villanova.edu/libtech/2012/07/19/moving-vufind-to-zend-framework-2-part-4-command-line-tools/
>
> I'm sharing this for three reasons:
>
> 1.) I thought it might be of interest to others facing the same problems.
> 2.) I'm hoping that someone with more Zend Framework 2 knowledge may have some comments on how I could do this better.
> 3.) Perhaps it can advance some of the conversations about the CLI RFC (http://framework.zend.com/wiki/display/ZFDEV2/RFC+-+CLI).
>
> If nothing else, it demonstrates a few needs that aren't explicitly laid out in the current RFC:
>
> 1.) Sharing bootstrapping between web and CLI apps (possibly addressed by the final note in the document).
> 2.) The need for real-time feedback in addition to generation of a response object.
> 3.) The need for setting an exit status (presumably a necessary feature of the CLI response object).
>
> I hope this is helpful, and I'll be happy to discuss it further if anyone is interested.
>
> - Demian

[Artur Bodera]

On Thu, Jul 19, 2012 at 5:35 PM, Demian Katz <[hidden email]> wrote:

1.) Sharing bootstrapping between web and CLI apps (possibly addressed by the final note in the document).

Done.

 

2.) The need for real-time feedback in addition to generation of a response object.

Done, and already possible.

 

3.) The need for setting an exit status (presumably a necessary feature of the CLI response object).

Done - just set errorLevel in the response or View\Model\ConsoleModel that your controller action returns.

It's not merged with ZF2 yet, but you can read more in PR here: 

https://github.com/zendframework/zf2/pull/1945

Documentation and a quick start guide will follow soon ...

-- 
      __
     /.)\   [phone]
     \(./   [hidden email]