Multi-language Grails user guides

[pledbrook]

Hi,

I have created a branch on the grails-doc project that supports
multiple language versions of the user guide:

    https://github.com/grails/grails-doc/tree/multi-lang

The basic idea is that you put the language-specific guide source in
'src/<lang>'. In the current branch I have 'src/fr/guide' and
'src/fr/ref'. The build will then automatically generate an extra user
guide based on that language, so we would end up with URLs like
/doc/latest/fr/guide/single.html.

The build also automatically generates a bunch of tasks based on the
language directories under 'src':

* publishGuide_<lang>
* publishPdf_<lang>

so if you only want to generate one of them, you just run the
corresponding tasks. For example publishGuide_fr and publishPdf_fr.

I wanted to run this by people to see whether anyone can see any
problems with the approach. If not, I could commit these changes and
then create a public clone that people can commit directly to. Would
that help with contributions to translations of the user guide?

Thanks,

Peter

--
Peter Ledbrook
Grails Advocate
SpringSource - A Division of VMware

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email

[lucastex]

Hi Peter,

This is great... 

Several times I had the idea to translate the guide to pt_br, the main point that stopped me, was how to make it synced to the main guide in english.

How do you think this could be done? 

Main point is, when another grails version comes out, just "generating" the docs (in all languages) does not guarantee that all languages will be already translated new features.

Other thing, is that when adding small pieces of docs (or correcting code snippets), in the main branch, how to "sync" these changes to other languages, since who is writing in english is not probably the same one that will translate to arabic :P

Again, congrats, awesome idea :)

[]s, 

Lucas Teixeira

On Mon, Aug 15, 2011 at 1:13 PM, Peter Ledbrook <[hidden email]> wrote:

Hi,

I have created a branch on the grails-doc project that supports
multiple language versions of the user guide:

   https://github.com/grails/grails-doc/tree/multi-lang

The basic idea is that you put the language-specific guide source in
'src/<lang>'. In the current branch I have 'src/fr/guide' and
'src/fr/ref'. The build will then automatically generate an extra user
guide based on that language, so we would end up with URLs like
/doc/latest/fr/guide/single.html.

The build also automatically generates a bunch of tasks based on the
language directories under 'src':

* publishGuide_<lang>
* publishPdf_<lang>

so if you only want to generate one of them, you just run the
corresponding tasks. For example publishGuide_fr and publishPdf_fr.

I wanted to run this by people to see whether anyone can see any
problems with the approach. If not, I could commit these changes and
then create a public clone that people can commit directly to. Would
that help with contributions to translations of the user guide?

Thanks,

Peter

--
Peter Ledbrook
Grails Advocate
SpringSource - A Division of VMware

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

   http://xircles.codehaus.org/manage_email

[pledbrook]

> Several times I had the idea to translate the guide to pt_br, the main point
> that stopped me, was how to make it synced to the main guide in english.
> How do you think this could be done?

Not sure what you're asking here. The only thing I can think of at the
moment is that translators track the commit history for src/guide and
src/ref. Any new commits should be translated. This does raise the
question of how to track what's already been translated, but perhaps
we can do something in the build to help.

For example, what you probably want to do is see all commits on
'src/guide' and 'src/ref' since the last commit that was translated.
So, we could record which commits have been worked on, perhaps in the
commit messages of the translations. The build could process these to
find out which commits haven't been translated yet. I don't know if
this is workable though.

Also, the basic guide needs translating, not just the new commits.
This means you'll have a bunch of commits on a translation directory
that don't have corresponding ones on 'src/guide' and 'src/ref'.

> Main point is, when another grails version comes out, just "generating" the
> docs (in all languages) does not guarantee that all languages will be
> already translated new features.

Correct. Unfortunately, I can't see a way of automatically validating
a guide translation, so we'd have to have some process involving
trust. For example, someone tells us that a guide is up to date for a
particular version so we can enable it. We could certainly verify that
all gdoc files have corresponding versions in the translation, but
that's about it.

I don't think this will be easy, but hopefully we can get some useful
concrete plans out of this thread.

Peter

--
Peter Ledbrook
Grails Advocate
SpringSource - A Division of VMware

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email

[lucastex]

On Tue, Aug 16, 2011 at 5:18 AM, Peter Ledbrook <[hidden email]> wrote:

> Several times I had the idea to translate the guide to pt_br, the main point
> that stopped me, was how to make it synced to the main guide in english.
> How do you think this could be done?

Not sure what you're asking here. The only thing I can think of at the
moment is that translators track the commit history for src/guide and
src/ref. Any new commits should be translated. This does raise the
question of how to track what's already been translated, but perhaps
we can do something in the build to help.

For example, what you probably want to do is see all commits on
'src/guide' and 'src/ref' since the last commit that was translated.
So, we could record which commits have been worked on, perhaps in the
commit messages of the translations. The build could process these to
find out which commits haven't been translated yet. I don't know if
this is workable though.

Also, the basic guide needs translating, not just the new commits.
This means you'll have a bunch of commits on a translation directory
that don't have corresponding ones on 'src/guide' and 'src/ref'.

Yes Peter, you got the point I was talking about.

How to keep track of this. 

 

> Main point is, when another grails version comes out, just "generating" the
> docs (in all languages) does not guarantee that all languages will be
> already translated new features.

Correct. Unfortunately, I can't see a way of automatically validating
a guide translation, so we'd have to have some process involving
trust. For example, someone tells us that a guide is up to date for a
particular version so we can enable it. We could certainly verify that
all gdoc files have corresponding versions in the translation, but
that's about it.

I don't think this will be easy, but hopefully we can get some useful
concrete plans out of this thread.

I was thinking and had an idea.

We could track commits on src/ref/en (an 'en' directory would help things out I think) and src/guide/en/ (or even src/en/guide and src/en/ref) between grails releases and keep track on what version of the guide has been translated.

For instance, I'd translate the User Guide for 2.0 totally, and later, when 2.1, or 2.0.1, or any other new release cames out, we could generate a list of commits automatically of what had been done in src/en directory for example and open a new JIRA issue, something like: "update grails docs in portuguese to 2.0.1" with the commits delta that sould be translated.

This kind of tracking it is not that difficult to do (i imagine), and could help, probably.

what do you think?

Lucas Teixeira

 

Peter

--
Peter Ledbrook
Grails Advocate
SpringSource - A Division of VMware

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

   http://xircles.codehaus.org/manage_email

[pledbrook]

> I was thinking and had an idea.
> We could track commits on src/ref/en (an 'en' directory would help things
> out I think) and src/guide/en/ (or even src/en/guide and src/en/ref) between
> grails releases and keep track on what version of the guide has been
> translated.
> For instance, I'd translate the User Guide for 2.0 totally, and later, when
> 2.1, or 2.0.1, or any other new release cames out, we could generate a list
> of commits automatically of what had been done in src/en directory for
> example and open a new JIRA issue, something like: "update grails docs in
> portuguese to 2.0.1" with the commits delta that sould be translated.
> This kind of tracking it is not that difficult to do (i imagine), and could
> help, probably.
> what do you think?

I've just verified that I can move the source to 'src/en' without
affecting the generated HTML (it would still be at /doc/latest rather
than /doc/latest/en).

The above is certainly one approach you can take. You could either
generate a diff file and work to incorporate that, or generate a list
of commit IDs with links to GitHub. The downside is that it won't work
so well if you want to keep up to date between versions.

For that, you could create a tag that tracks progress in the English source:

    git tag -f pt_BR <commit>

I suspect though that neither approach will work particularly well if
you have multiple contributors to a translation who translate
individual commits here and there or even just translate sections with
no reference back to the original commits. For example, a user may
notice that a particular page is out of date and decide to update the
translation source, comparing it to the latest English guide.

Also, Marc pointed out that /doc/latest may become problematic with
translations. If the English guide is at 3.0 but the French guide is
still at 2.1, what should /doc/latest/fr show? I'm tempted to show a
page that says the guide isn't available for the latest version of
Grails but with a link to the most recent version (2.1).

Peter

--
Peter Ledbrook
Grails Advocate
SpringSource - A Division of VMware

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email

[pledbrook]

> I've just verified that I can move the source to 'src/en' without
> affecting the generated HTML (it would still be at /doc/latest rather
> than /doc/latest/en).

And I have now pushed the change to the multi-lang branch on GitHub.

Peter

--
Peter Ledbrook
Grails Advocate
SpringSource - A Division of VMware

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email

[lucastex]

On Tue, Aug 16, 2011 at 10:49 AM, Peter Ledbrook <[hidden email]> wrote:

> I was thinking and had an idea.
> We could track commits on src/ref/en (an 'en' directory would help things
> out I think) and src/guide/en/ (or even src/en/guide and src/en/ref) between
> grails releases and keep track on what version of the guide has been
> translated.
> For instance, I'd translate the User Guide for 2.0 totally, and later, when
> 2.1, or 2.0.1, or any other new release cames out, we could generate a list
> of commits automatically of what had been done in src/en directory for
> example and open a new JIRA issue, something like: "update grails docs in
> portuguese to 2.0.1" with the commits delta that sould be translated.
> This kind of tracking it is not that difficult to do (i imagine), and could
> help, probably.
> what do you think?

I've just verified that I can move the source to 'src/en' without
affecting the generated HTML (it would still be at /doc/latest rather
than /doc/latest/en).

Cool. Much better https://github.com/grails/grails-doc/tree/multi-lang/src/en   :)

The above is certainly one approach you can take. You could either
generate a diff file and work to incorporate that, or generate a list
of commit IDs with links to GitHub. The downside is that it won't work
so well if you want to keep up to date between versions.

For that, you could create a tag that tracks progress in the English source:

   git tag -f pt_BR <commit>

I suspect though that neither approach will work particularly well if
you have multiple contributors to a translation who translate
individual commits here and there or even just translate sections with
no reference back to the original commits. For example, a user may
notice that a particular page is out of date and decide to update the
translation source, comparing it to the latest English guide.

No prob at all, I think the commit list would work at first...

 

Also, Marc pointed out that /doc/latest may become problematic with
translations. If the English guide is at 3.0 but the French guide is
still at 2.1, what should /doc/latest/fr show? I'm tempted to show a
page that says the guide isn't available for the latest version of
Grails but with a link to the most recent version (2.1).

+1 for the page.

When will this be on the master branch? After 2.0 stable or before?

Thanks Peter,

[]s,

 

 

Peter

--
Peter Ledbrook
Grails Advocate
SpringSource - A Division of VMware

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

   http://xircles.codehaus.org/manage_email

[pledbrook]

> +1 for the page.
> When will this be on the master branch? After 2.0 stable or before?
> Thanks Peter,

If there are no objections I can have it on master straight away. I will have to sort out the "latest Grails version not available yet" page before M2 though.

Peter

--
Peter Ledbrook
Grails Advocate
SpringSource - A Division of VMware

[pledbrook]

Some ideas from Tsuyoshi Yamamoto, who's maintaining the Japanese user guide:

-----

Hi Peter,
That's great!! I'd try that!

I've been thinking about, how do I check documents update.
I'm trying a wiki macro to leave a original document.
so, it can be useful for checking update.
you can check it on my repository.

for example.
1. Copy all English docs into ja directory.
2. warp the original words with {hidden} macro.
3. put translated words below.
* we can check which sentence is updated later.
* I use this on translate gdoc file,not on original.
----code gdoc----
{hidden}original document {hidden}
Translated documents.

{hidden}original document line 2{hidden}
Translated documents line 2.
---------

My Project repo:
https://github.com/jggug/grails-doc-ja

HiddenMacro:
https://github.com/jggug/grails-doc-ja/blob/master/src/main/groovy/macros/HiddenMacro.groovy

Here's how i use macro.
https://github.com/jggug/grails-doc-ja/blob/master/src/ja/guide/theWebLayer/gsp.gdoc


And, I put simple option to view original document with translated
document by using javascript bookmarklet.
Open URL below,
http://grails.jp/doc/2.0.x/guide/theWebLayer.html

try this Bookmarklet to view english document inline:
javascript:$A(document.getElementsByClassName("hidden-block")).each(Element.show);

-----------

It wouldn't be hard to incorporate the Hidden macro into the main
Grails user guide build. In fact, I'll probably do that. It's then up
to the translators whether they want to use it or not.

Thoughts?

Peter

--
Peter Ledbrook
Grails Advocate
SpringSource - A Division of VMware

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email

[Graeme Rocher-4]

hidden macro looks like a good idea

Cheers

On Wed, Aug 17, 2011 at 12:01 PM, Peter Ledbrook <[hidden email]> wrote:

> Some ideas from Tsuyoshi Yamamoto, who's maintaining the Japanese user guide:
>
> -----
>
> Hi Peter,
> That's great!! I'd try that!
>
> I've been thinking about, how do I check documents update.
> I'm trying a wiki macro to leave a original document.
> so, it can be useful for checking update.
> you can check it on my repository.
>
> for example.
> 1. Copy all English docs into ja directory.
> 2. warp the original words with {hidden} macro.
> 3. put translated words below.
> * we can check which sentence is updated later.
> * I use this on translate gdoc file,not on original.
> ----code gdoc----
> {hidden}original document {hidden}
> Translated documents.
>
> {hidden}original document line 2{hidden}
> Translated documents line 2.
> ---------
>
> My Project repo:
> https://github.com/jggug/grails-doc-ja
>
> HiddenMacro:
> https://github.com/jggug/grails-doc-ja/blob/master/src/main/groovy/macros/HiddenMacro.groovy
>
> Here's how i use macro.
> https://github.com/jggug/grails-doc-ja/blob/master/src/ja/guide/theWebLayer/gsp.gdoc
>
>
> And, I put simple option to view original document with translated
> document by using javascript bookmarklet.
> Open URL below,
> http://grails.jp/doc/2.0.x/guide/theWebLayer.html
>
> try this Bookmarklet to view english document inline:
> javascript:$A(document.getElementsByClassName("hidden-block")).each(Element.show);
>
> -----------
>
> It wouldn't be hard to incorporate the Hidden macro into the main
> Grails user guide build. In fact, I'll probably do that. It's then up
> to the translators whether they want to use it or not.
>
> Thoughts?
>
> Peter
>
> --
> Peter Ledbrook
> Grails Advocate
> SpringSource - A Division of VMware
>
> ---------------------------------------------------------------------
> To unsubscribe from this list, please visit:
>
>    http://xircles.codehaus.org/manage_email
>
>
>

--
Graeme Rocher
Grails Project Lead
SpringSource - A Division of VMware
http://www.springsource.com

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email

[lucastex]

Looks great,

Is Tsuyoshi Yamamoto on this list?

Would be great to see how is he checking for changes. 

[]s,

Lucas Teixeira

On Wed, Aug 17, 2011 at 7:13 AM, Graeme Rocher <[hidden email]> wrote:

hidden macro looks like a good idea

Cheers

On Wed, Aug 17, 2011 at 12:01 PM, Peter Ledbrook <[hidden email]> wrote:
> Some ideas from Tsuyoshi Yamamoto, who's maintaining the Japanese user guide:
>
> -----
>
> Hi Peter,
> That's great!! I'd try that!
>
> I've been thinking about, how do I check documents update.
> I'm trying a wiki macro to leave a original document.
> so, it can be useful for checking update.
> you can check it on my repository.
>
> for example.
> 1. Copy all English docs into ja directory.
> 2. warp the original words with {hidden} macro.
> 3. put translated words below.
> * we can check which sentence is updated later.
> * I use this on translate gdoc file,not on original.
> ----code gdoc----
> {hidden}original document {hidden}
> Translated documents.
>
> {hidden}original document line 2{hidden}
> Translated documents line 2.
> ---------
>
> My Project repo:
> https://github.com/jggug/grails-doc-ja
>
> HiddenMacro:
> https://github.com/jggug/grails-doc-ja/blob/master/src/main/groovy/macros/HiddenMacro.groovy
>
> Here's how i use macro.
> https://github.com/jggug/grails-doc-ja/blob/master/src/ja/guide/theWebLayer/gsp.gdoc
>
>
> And, I put simple option to view original document with translated
> document by using javascript bookmarklet.
> Open URL below,
> http://grails.jp/doc/2.0.x/guide/theWebLayer.html
>
> try this Bookmarklet to view english document inline:
> javascript:$A(document.getElementsByClassName("hidden-block")).each(Element.show);
>
> -----------
>
> It wouldn't be hard to incorporate the Hidden macro into the main
> Grails user guide build. In fact, I'll probably do that. It's then up
> to the translators whether they want to use it or not.
>
> Thoughts?
>
> Peter
>
> --
> Peter Ledbrook
> Grails Advocate
> SpringSource - A Division of VMware
>
> ---------------------------------------------------------------------
> To unsubscribe from this list, please visit:
>
>    http://xircles.codehaus.org/manage_email
>
>
>

--
Graeme Rocher
Grails Project Lead

SpringSource - A Division of VMware

http://www.springsource.com

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

   http://xircles.codehaus.org/manage_email

[lucastex]

IMO, this fits the first needs.

Might be better to define this asap, since people are already working on translated versions of the guide, and sooner gets defined, easier would be for them.

[]s,

Lucas Teixeira

On Wed, Aug 17, 2011 at 12:17 PM, Lucas F. A. Teixeira <[hidden email]> wrote:

Looks great,

Is Tsuyoshi Yamamoto on this list?

Would be great to see how is he checking for changes. 

[]s,

Lucas Teixeira

On Wed, Aug 17, 2011 at 7:13 AM, Graeme Rocher <[hidden email]> wrote:

hidden macro looks like a good idea

Cheers

On Wed, Aug 17, 2011 at 12:01 PM, Peter Ledbrook <[hidden email]> wrote:
> Some ideas from Tsuyoshi Yamamoto, who's maintaining the Japanese user guide:
>
> -----
>
> Hi Peter,
> That's great!! I'd try that!
>
> I've been thinking about, how do I check documents update.
> I'm trying a wiki macro to leave a original document.
> so, it can be useful for checking update.
> you can check it on my repository.
>
> for example.
> 1. Copy all English docs into ja directory.
> 2. warp the original words with {hidden} macro.
> 3. put translated words below.
> * we can check which sentence is updated later.
> * I use this on translate gdoc file,not on original.
> ----code gdoc----
> {hidden}original document {hidden}
> Translated documents.
>
> {hidden}original document line 2{hidden}
> Translated documents line 2.
> ---------
>
> My Project repo:
> https://github.com/jggug/grails-doc-ja
>
> HiddenMacro:
> https://github.com/jggug/grails-doc-ja/blob/master/src/main/groovy/macros/HiddenMacro.groovy
>
> Here's how i use macro.
> https://github.com/jggug/grails-doc-ja/blob/master/src/ja/guide/theWebLayer/gsp.gdoc
>
>
> And, I put simple option to view original document with translated
> document by using javascript bookmarklet.
> Open URL below,
> http://grails.jp/doc/2.0.x/guide/theWebLayer.html
>
> try this Bookmarklet to view english document inline:
> javascript:$A(document.getElementsByClassName("hidden-block")).each(Element.show);
>
> -----------
>
> It wouldn't be hard to incorporate the Hidden macro into the main
> Grails user guide build. In fact, I'll probably do that. It's then up
> to the translators whether they want to use it or not.
>
> Thoughts?
>
> Peter
>
> --
> Peter Ledbrook
> Grails Advocate
> SpringSource - A Division of VMware
>
> ---------------------------------------------------------------------
> To unsubscribe from this list, please visit:
>
>    http://xircles.codehaus.org/manage_email
>
>
>

--
Graeme Rocher
Grails Project Lead

SpringSource - A Division of VMware

http://www.springsource.com

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

   http://xircles.codehaus.org/manage_email

[Tsuyoshi Yamamoto]

Hi,

It would be great, if I could use this officially.

> Would be great to see how is he checking for changes.
There is no script for this yet.
My plan is write some simple Groovy script.


Cheers
----------------
Tsuyoshi Yamamoto


On Thu, Aug 18, 2011 at 12:06 PM, Lucas F. A. Teixeira
<[hidden email]> wrote:

> IMO, this fits the first needs.
> Might be better to define this asap, since people are already working on
> translated versions of the guide, and sooner gets defined, easier would be
> for them.
> []s,
> Lucas Teixeira
>
>
> On Wed, Aug 17, 2011 at 12:17 PM, Lucas F. A. Teixeira <[hidden email]>
> wrote:
>>
>> Looks great,
>> Is Tsuyoshi Yamamoto on this list?
>> Would be great to see how is he checking for changes.
>> []s,
>> Lucas Teixeira
>>
>>
>> On Wed, Aug 17, 2011 at 7:13 AM, Graeme Rocher <[hidden email]> wrote:
>>>
>>> hidden macro looks like a good idea
>>>
>>> Cheers
>>>
>>> On Wed, Aug 17, 2011 at 12:01 PM, Peter Ledbrook <[hidden email]>
>>> wrote:
>>> > Some ideas from Tsuyoshi Yamamoto, who's maintaining the Japanese user
>>> > guide:
>>> >
>>> > -----
>>> >
>>> > Hi Peter,
>>> > That's great!! I'd try that!
>>> >
>>> > I've been thinking about, how do I check documents update.
>>> > I'm trying a wiki macro to leave a original document.
>>> > so, it can be useful for checking update.
>>> > you can check it on my repository.
>>> >
>>> > for example.
>>> > 1. Copy all English docs into ja directory.
>>> > 2. warp the original words with {hidden} macro.
>>> > 3. put translated words below.
>>> > * we can check which sentence is updated later.
>>> > * I use this on translate gdoc file,not on original.
>>> > ----code gdoc----
>>> > {hidden}original document {hidden}
>>> > Translated documents.
>>> >
>>> > {hidden}original document line 2{hidden}
>>> > Translated documents line 2.
>>> > ---------
>>> >
>>> > My Project repo:
>>> > https://github.com/jggug/grails-doc-ja
>>> >
>>> > HiddenMacro:
>>> >
>>> > https://github.com/jggug/grails-doc-ja/blob/master/src/main/groovy/macros/HiddenMacro.groovy
>>> >
>>> > Here's how i use macro.
>>> >
>>> > https://github.com/jggug/grails-doc-ja/blob/master/src/ja/guide/theWebLayer/gsp.gdoc
>>> >
>>> >
>>> > And, I put simple option to view original document with translated
>>> > document by using javascript bookmarklet.
>>> > Open URL below,
>>> > http://grails.jp/doc/2.0.x/guide/theWebLayer.html
>>> >
>>> > try this Bookmarklet to view english document inline:
>>> >
>>> > javascript:$A(document.getElementsByClassName("hidden-block")).each(Element.show);
>>> >
>>> > -----------
>>> >
>>> > It wouldn't be hard to incorporate the Hidden macro into the main
>>> > Grails user guide build. In fact, I'll probably do that. It's then up
>>> > to the translators whether they want to use it or not.
>>> >
>>> > Thoughts?
>>> >
>>> > Peter
>>> >
>>> > --
>>> > Peter Ledbrook
>>> > Grails Advocate
>>> > SpringSource - A Division of VMware
>>> >
>>> > ---------------------------------------------------------------------
>>> > To unsubscribe from this list, please visit:
>>> >
>>> >    http://xircles.codehaus.org/manage_email
>>> >
>>> >
>>> >
>>>
>>>
>>>
>>> --
>>> Graeme Rocher
>>> Grails Project Lead
>>> SpringSource - A Division of VMware
>>> http://www.springsource.com
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe from this list, please visit:
>>>
>>>    http://xircles.codehaus.org/manage_email
>>>
>>>
>>
>
>

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email

[pledbrook]

> IMO, this fits the first needs.
> Might be better to define this asap, since people are already working on
> translated versions of the guide, and sooner gets defined, easier would be
> for them.

Sorry, not sure what you're referring to exactly here. What needs defining asap?

Thanks,

Peter

--
Peter Ledbrook
Grails Advocate
SpringSource - A Division of VMware

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email

[lucastex]

If I'm not wrong, we're discussing about how to "know" when the original (english) docs has changed to keep the translated version synced. 

I like Tsuyoshi's idea to keep the original english source in the same file under some tags, and use a groovy script to check the original file content and the {hidden} content in the translated file to see what've changed.

I see people motivated on translating it (fr, pt_pt, pt_br, turkish, etc), and IMO, having some "correct way" to do this, would be better and easier.

[]s, 

Lucas Teixeira

On Thu, Aug 18, 2011 at 5:47 AM, Peter Ledbrook <[hidden email]> wrote:

> IMO, this fits the first needs.
> Might be better to define this asap, since people are already working on
> translated versions of the guide, and sooner gets defined, easier would be
> for them.

Sorry, not sure what you're referring to exactly here. What needs defining asap?

Thanks,

Peter

--
Peter Ledbrook
Grails Advocate
SpringSource - A Division of VMware

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

   http://xircles.codehaus.org/manage_email

[pledbrook]

> If I'm not wrong, we're discussing about how to "know" when the original
> (english) docs has changed to keep the translated version synced.
> I like Tsuyoshi's idea to keep the original english source in the same file
> under some tags, and use a groovy script to check the original file content
> and the {hidden} content in the translated file to see what've changed.
> I see people motivated on translating it (fr, pt_pt, pt_br, turkish, etc),
> and IMO, having some "correct way" to do this, would be better and easier.

OK, understood. I think such a Groovy script would be non-trivial, but
I'll have a think about it. I'm also attempting to get the {hidden}
macro into the build - just having an issue with it a the moment.
Hopefully the Gradle team can help me with that. Once that's ready,
I'll put some details of use in the project README.

Peter

--
Peter Ledbrook
Grails Advocate
SpringSource - A Division of VMware

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email

[pledbrook]

> It would be great, if I could use this officially.

I have added the {hidden} macro to the grails-doc project and it's now
available on the public fork:

     https://github.com/pledbrook/grails-doc

See the README on that page for more details. If you think the README
could be improved let me know or simply commit some changes!

Note that the Javascript function for toggling the hidden blocks will
only work if you build the user guide against grails-core HEAD. I
usually clone grails-core to the same directory as grails-doc, build
it using

    ./gradlew install

and then build the user guide with

    ./gradlew -Dgrails.home=../grails-core -Ddisable.groovydocs=true docs

You can then add the URL "javascript:toggleHidden();" as a bookmark
and toggle the hidden blocks on and off.

Cheers,

Peter

--
Peter Ledbrook
Grails Advocate
SpringSource - A Division of VMware

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email

[Tsuyoshi Yamamoto]

That's nice!
Thank you!

Cheers,
----------------
Tsuyoshi Yamamoto

On Fri, Aug 19, 2011 at 3:59 PM, Peter Ledbrook <[hidden email]> wrote:

>> It would be great, if I could use this officially.
>
> I have added the {hidden} macro to the grails-doc project and it's now
> available on the public fork:
>
>     https://github.com/pledbrook/grails-doc
>
> See the README on that page for more details. If you think the README
> could be improved let me know or simply commit some changes!
>
> Note that the Javascript function for toggling the hidden blocks will
> only work if you build the user guide against grails-core HEAD. I
> usually clone grails-core to the same directory as grails-doc, build
> it using
>
>    ./gradlew install
>
> and then build the user guide with
>
>    ./gradlew -Dgrails.home=../grails-core -Ddisable.groovydocs=true docs
>
> You can then add the URL "javascript:toggleHidden();" as a bookmark
> and toggle the hidden blocks on and off.
>
> Cheers,
>
> Peter
>
> --
> Peter Ledbrook
> Grails Advocate
> SpringSource - A Division of VMware
>
> ---------------------------------------------------------------------
> To unsubscribe from this list, please visit:
>
>    http://xircles.codehaus.org/manage_email
>
>
>

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email

[tomas lin]

Hi,

In a lot of cases, it makes sense to start with an automatic
translation instead of the English language version of the document.

This will allow non-native speakers to contribute to the project.
Writing a script to do the automatic translation is fairly trivial, as
can be seen in both the autotranslate and translate plugins.

I wonder if it would be possible to also have { automatic } {
automatic } flag in translated files that gets ignored. Then whatever
mechanism is used to generate the translations would be able to new
translations into { automatic } { automatic }

On Fri, Aug 19, 2011 at 8:22 AM, Tsuyoshi Yamamoto <[hidden email]> wrote:

> That's nice!
> Thank you!
>
> Cheers,
> ----------------
> Tsuyoshi Yamamoto
>
> On Fri, Aug 19, 2011 at 3:59 PM, Peter Ledbrook <[hidden email]> wrote:
>>> It would be great, if I could use this officially.
>>
>> I have added the {hidden} macro to the grails-doc project and it's now
>> available on the public fork:
>>
>>     https://github.com/pledbrook/grails-doc
>>
>> See the README on that page for more details. If you think the README
>> could be improved let me know or simply commit some changes!
>>
>> Note that the Javascript function for toggling the hidden blocks will
>> only work if you build the user guide against grails-core HEAD. I
>> usually clone grails-core to the same directory as grails-doc, build
>> it using
>>
>>    ./gradlew install
>>
>> and then build the user guide with
>>
>>    ./gradlew -Dgrails.home=../grails-core -Ddisable.groovydocs=true docs
>>
>> You can then add the URL "javascript:toggleHidden();" as a bookmark
>> and toggle the hidden blocks on and off.
>>
>> Cheers,
>>
>> Peter
>>
>> --
>> Peter Ledbrook
>> Grails Advocate
>> SpringSource - A Division of VMware
>>
>> ---------------------------------------------------------------------
>> To unsubscribe from this list, please visit:
>>
>>    http://xircles.codehaus.org/manage_email
>>
>>
>>
>
> ---------------------------------------------------------------------
> To unsubscribe from this list, please visit:
>
>    http://xircles.codehaus.org/manage_email
>
>
>

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email

[pledbrook]

> In a lot of cases, it makes sense to start with an automatic
> translation instead of the English language version of the document.
>
> This will allow non-native speakers to contribute to the project.
> Writing a script to do the automatic translation is fairly trivial, as
> can be seen in both the autotranslate and translate plugins.

I don't agree with the trivial :) First, Google Translate is now a
paid service. Second, the Microsoft Translator API has daily quota
limits. That quota could make any script non-trivial. Also, I'm not
sure that it's going to be particularly trivial to write a gdoc
parser, which would be needed to process them for translation
(ignoring code blocks, etc.). That said, it's an interesting idea and
may be worth playing around with at some point.

Cheers,

Peter

--
Peter Ledbrook
Grails Advocate
SpringSource - A Division of VMware

---------------------------------------------------------------------
To unsubscribe from this list, please visit:

    http://xircles.codehaus.org/manage_email