New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Documentation for Manage Translations #4470

Merged
merged 6 commits into from Aug 23, 2018

Conversation

Projects
None yet
3 participants
@humitos
Member

humitos commented Aug 3, 2018

Guide explaining two different flows to manage translation: manual and using Transifex.

Documentation for Manage Translations
Guide explaining two different flows to manage translation: manual and
using Transifex.

@humitos humitos added this to the I18n improvements milestone Aug 6, 2018

@humitos humitos requested a review from rtfd/core Aug 6, 2018

@humitos

This comment has been minimized.

Show comment
Hide comment
@humitos

humitos Aug 6, 2018

Member

@ewjoachim In case you have some time, would you mind taking a look at this guide that I wrote to help users to keep their docs updated and translated into different languages? Thanks! :)

Member

humitos commented Aug 6, 2018

@ewjoachim In case you have some time, would you mind taking a look at this guide that I wrote to help users to keep their docs updated and translated into different languages? Thanks! :)

@ewjoachim

That was really good :) A few comments.

"It supports :ref:`Sphinx <sphinx>` docs written with reStructuredText."
msgstr ""
"FILL HERE BY TARGET LANGUAGE FILL HERE BY TARGET LANGUAGE FILL HERE "
"BY TARGET LANGUAGE :ref:`Sphinx <sphinx>` FILL HERE."

This comment has been minimized.

@ewjoachim

ewjoachim Aug 7, 2018

Contributor

For a semi-manual process, it may be interesting to mention specialized (but non-cloud) tools such as poedit

@ewjoachim

ewjoachim Aug 7, 2018

Contributor

For a semi-manual process, it may be interesting to mention specialized (but non-cloud) tools such as poedit

This comment has been minimized.

@humitos

humitos Aug 7, 2018

Member

I like it!

@humitos

humitos Aug 7, 2018

Member

I like it!

Using Transifex
~~~~~~~~~~~~~~~
Transifex_ is a platform that simplifies the manipulation of ``.po`` files and offers many useful features to make the translation process as smooth as possible.

This comment has been minimized.

@ewjoachim

ewjoachim Aug 7, 2018

Contributor

I guess given we're about to make a nice advertising for Transifex services (which is fine by me), it would be fair to mention the competition and their relationship with open-source projects.

Transifex:

We offer Transifex for free to Open Source projects that have no funding, revenue, and/or commercialization model
https://docs.transifex.com/projects/open-source-project

Crowdin:
Free too, with conditions

Zanata:
Free, open source, self-hostable (by Red Hat), but as far as I know, less features
http://zanata.org/

And then there's PhraseApp, Smartling and many others.

@ewjoachim

ewjoachim Aug 7, 2018

Contributor

I guess given we're about to make a nice advertising for Transifex services (which is fine by me), it would be fair to mention the competition and their relationship with open-source projects.

Transifex:

We offer Transifex for free to Open Source projects that have no funding, revenue, and/or commercialization model
https://docs.transifex.com/projects/open-source-project

Crowdin:
Free too, with conditions

Zanata:
Free, open source, self-hostable (by Red Hat), but as far as I know, less features
http://zanata.org/

And then there's PhraseApp, Smartling and many others.

This comment has been minimized.

@humitos

humitos Aug 7, 2018

Member

Good point.

This was something that bothered to me while I was writing this guide. The question was: "Why we are suggesting a non-free solution?" I read that note that you mention here, but it still made me noise at that time.

I commented this to @agjohnson and he said that maybe it does worth to have multiples guides instead just one. Like:

  • How to use Transifex and Read the Docs?
  • How to use Crowdin and Read the Docs?
  • etc

I think this is the direction that I would like to follow, but I do not have experience with these other tools and this will take me some time to read, test the flow and write the docs. So, I'd say that we could have a initial guide (as this one) and work in the other guides soon.

Maybe, we could mention the other solutions (name and link) and add a note saying that we are working on writing other guides for them and contributions are welcomed :)

What do you think?

@humitos

humitos Aug 7, 2018

Member

Good point.

This was something that bothered to me while I was writing this guide. The question was: "Why we are suggesting a non-free solution?" I read that note that you mention here, but it still made me noise at that time.

I commented this to @agjohnson and he said that maybe it does worth to have multiples guides instead just one. Like:

  • How to use Transifex and Read the Docs?
  • How to use Crowdin and Read the Docs?
  • etc

I think this is the direction that I would like to follow, but I do not have experience with these other tools and this will take me some time to read, test the flow and write the docs. So, I'd say that we could have a initial guide (as this one) and work in the other guides soon.

Maybe, we could mention the other solutions (name and link) and add a note saying that we are working on writing other guides for them and contributions are welcomed :)

What do you think?

This comment has been minimized.

@ewjoachim

ewjoachim Aug 7, 2018

Contributor

Wow, you seem way more ambitious than me :D I would tend to just mention names and links as you said, and maybe a link to every project documentation.

If those projects have documentation, then they might be more precise and up to date than ours will be (given we're really following a classic use case here).

If those projects don't have documentation... Do we really want to link to them ? :D

That being said, I'm totally ok keeping the transifex doc, especially now it's been written, because if there's at least one doc, then it's easier to understand what we're trying to do and adapt it to another tool.

Lastly, there's another alternative if you want to explore it : a "logical" documentation that would explain the steps and you can see examples with different tools. Something like

Upload the sources:
with transifex | with crowdin | ...
[panel that would change depending on the click above]

This would maybe help people understand that whatever the tools, the steps are the same.

@ewjoachim

ewjoachim Aug 7, 2018

Contributor

Wow, you seem way more ambitious than me :D I would tend to just mention names and links as you said, and maybe a link to every project documentation.

If those projects have documentation, then they might be more precise and up to date than ours will be (given we're really following a classic use case here).

If those projects don't have documentation... Do we really want to link to them ? :D

That being said, I'm totally ok keeping the transifex doc, especially now it's been written, because if there's at least one doc, then it's easier to understand what we're trying to do and adapt it to another tool.

Lastly, there's another alternative if you want to explore it : a "logical" documentation that would explain the steps and you can see examples with different tools. Something like

Upload the sources:
with transifex | with crowdin | ...
[panel that would change depending on the click above]

This would maybe help people understand that whatever the tools, the steps are the same.

$ sphinx-build -b gettext . _build/gettext
.. For the manual workflow, we need to run this command

This comment has been minimized.

@ewjoachim

ewjoachim Aug 7, 2018

Contributor

I'm far (like, quite) from an rst expert, and I don't know enough of the syntax to understand the #. but the fact this one is the only one to begin differently seems noticeable (I bet I'm gonna learn something today :D )

@ewjoachim

ewjoachim Aug 7, 2018

Contributor

I'm far (like, quite) from an rst expert, and I don't know enough of the syntax to understand the #. but the fact this one is the only one to begin differently seems noticeable (I bet I'm gonna learn something today :D )

This comment has been minimized.

@humitos

humitos Aug 7, 2018

Member

He he :)

The #. is to define a enumerated (automatically) list: http://docutils.sourceforge.net/docs/user/rst/quickref.html#enumerated-lists

When the line starts with .. it's just a comment that won't appear in the renderized (html, pdf, etc) version: http://docutils.sourceforge.net/docs/user/rst/quickref.html#comments

@humitos

humitos Aug 7, 2018

Member

He he :)

The #. is to define a enumerated (automatically) list: http://docutils.sourceforge.net/docs/user/rst/quickref.html#enumerated-lists

When the line starts with .. it's just a comment that won't appear in the renderized (html, pdf, etc) version: http://docutils.sourceforge.net/docs/user/rst/quickref.html#comments

This comment has been minimized.

@ewjoachim

ewjoachim Aug 7, 2018

Contributor

But then I don't understand wyl this line in particular should be a comment ?

(Or was your "he he" a mark that it shouldn't ?)

@ewjoachim

ewjoachim Aug 7, 2018

Contributor

But then I don't understand wyl this line in particular should be a comment ?

(Or was your "he he" a mark that it shouldn't ?)

This comment has been minimized.

@humitos

humitos Aug 7, 2018

Member

But then I don't understand wyl this line in particular should be a comment ?

I noted as a comment because I wanted to mention it but I thought that it breaks the summary that I was describing, which it was all based on Transifex since it's the one that we use under RTD.

(Or was your "he he" a mark that it shouldn't ?)

Nope, it didn't mean that. Just made me fun that there was a comment in the middle of nowhere without any kind of explanation :)

I'm not sure yet how to include it. I mean, maybe this section needs some more work to make the mention of these command in a proper way.

@humitos

humitos Aug 7, 2018

Member

But then I don't understand wyl this line in particular should be a comment ?

I noted as a comment because I wanted to mention it but I thought that it breaks the summary that I was describing, which it was all based on Transifex since it's the one that we use under RTD.

(Or was your "he he" a mark that it shouldn't ?)

Nope, it didn't mean that. Just made me fun that there was a comment in the middle of nowhere without any kind of explanation :)

I'm not sure yet how to include it. I mean, maybe this section needs some more work to make the mention of these command in a proper way.

@ericholscher ericholscher merged commit a59c87f into master Aug 23, 2018

1 check passed

continuous-integration/travis-ci/pr The Travis CI build passed
Details
@ericholscher

This comment has been minimized.

Show comment
Hide comment
@ericholscher

ericholscher Aug 23, 2018

Member

This is great. Want to have this live!

Member

ericholscher commented Aug 23, 2018

This is great. Want to have this live!

@stsewd stsewd deleted the humitos/docs/translations branch Aug 23, 2018

@humitos humitos referenced this pull request Aug 23, 2018

Open

Improve Manage Translations guide #4564

0 of 2 tasks complete
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment