Documentation for Manage Translations #4470
Conversation
Guide explaining two different flows to manage translation: manual and using Transifex.
docs/guides/manage-translations.rst
Outdated
| .. tip:: | ||
|
|
||
| We recommend configuring Sphinx to use :ref:`sphinx:std:confval:gettext_uuid` as ``True`` | ||
| and also :ref:`sphinx:std:confval:gettext_compact` as ``False`` to generate ``.pot`` files. |
There was a problem hiding this comment.
I couldn't make intersphinx work here.
humitos
removed
the
PR: work in progress
|
@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! :) |
| "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." |
There was a problem hiding this comment.
For a semi-manual process, it may be interesting to mention specialized (but non-cloud) tools such as poedit
| 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. |
There was a problem hiding this comment.
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.
There was a problem hiding this comment.
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?
There was a problem hiding this comment.
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 |
There was a problem hiding this comment.
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 )
There was a problem hiding this comment.
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
There was a problem hiding this comment.
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 ?)
There was a problem hiding this comment.
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.
|
This is great. Want to have this live! |
Guide explaining two different flows to manage translation: manual and using Transifex.