Skip to content

Translations #1155

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.

Sign up for GitHub

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

Jump to bottom
Open
howiezhao opened this issue Jan 21, 2020 · 33 comments
Open

Translations #1155

howiezhao opened this issue Jan 21, 2020 · 33 comments

Comments

@howiezhao
Copy link

This is a great community, I can help translate this site into Chinese, how do i start?
@janbrohl
Copy link

I would assume translation could be done using sphinx-intl but I have not tried it.

I would gladly help with a German translation.

@plaindocs
Copy link
Contributor

Translating the site would be a huge task for any individual! Do either of you have ideas on where you'd like to start?

http://www.writethedocs.org/guide/ probably makes sense, but even then there is a lot of content.

I'm happy to do some work around setting up both languages for translation if you're still interested in this.

@janbrohl
Copy link

I am.

@howiezhao
Copy link
Author

@plaindocs This is a good idea, I plan to start translating from the guide.

@plaindocs
Copy link
Contributor

Hey, I got caught up in stuff - I'll try to test out intl in a week or so.

@howiezhao
Copy link
Author

@plaindocs OK

@plaindocs plaindocs mentioned this issue Mar 5, 2020
Closed
@plaindocs
Copy link
Contributor

Hi @janbrohl how familar are you with sphinx-intl?

We're using a datatemplate extension which doesn't seem to play nice with sphinx-intl.
Not sure how easy it would be to just grab a subset of the docs (the Guide) and translate those?

@janbrohl
Copy link

janbrohl commented Mar 6, 2020 •
edited
Loading

I have read https://www.sphinx-doc.org/en/master/usage/advanced/intl.html only.

If you are using sphinxcontrib.datatemplates - I am a maintainer of that package. Please open an issue there as we have not looked into compatibility there at all yet.

(Forgot to mention earlier: I'd start translation on the guide, too.)

@plaindocs plaindocs mentioned this issue Mar 6, 2020
Closed
@plaindocs
Copy link
Contributor

We're using a fork of that (was needed to add some functionality that might well now be available) so I'll need to test that out as well.

@Stolzenhain
Copy link

If you are using sphinxcontrib.datatemplates - I am a maintainer of that package. Please open an issue there as we have not looked into compatibility there at all yet.

(Forgot to mention earlier: I'd start translation on the guide, too.)

We could start producing translation drafts somewhere till the buidl setup is sorted out.

@janbrohl Two quick question concerning contribution from your experience:

  1. Any advice on structrual conventions we need to respect while creating .rst files in different languages? Do we simply add an extension to the filename?
  2. By what measure are we tracking document changes happening –after– the initial translation? Are we referencing commit IDs or is there an automatic way of – say – tracking changes newer than the referenced translation?

@janbrohl
Copy link

  1. I don't know about structural conventions. Sphinx does insert language-based pieces of text in the generated html so I would suggest creating technically separate folders or branches with a conf.py each and link via Intersphinx. This would also enable us using localized paths/filenames. For gettext based translation there would only be a locales directory containing translations for pieces of text plus some config.
    There may be different conventions on text structuring in different languages/cultures but for german, a sentence by sentence translation would normally not feel off. On the tech side it is important to have UTF encoded rst files for translations.
  2. For a gettext-based aproach, I suppose there should be warnings for untranslated blocks of text when changing only the english version, so this way, tracking the english version with all translations would be simple but also required for a correct full build. (For exact, up-to-date translations the gettext appoach seems better.)
    For the separated approach: If the different versions don't need to be very direct translations we would see some natural drift needing a bit of synchronization work but offering more freedom for improvements.
    I don't know of any existing solutions to this tracking-problem but an option for tracking would be to add a file for each translation (eg. translation-targets.yml) stating which page aims for which version like
de/docs/guide/loslegen.rst:
  target: en/docs/guide/starting.rst
  target-version: 1.2.3
  target-commit: abcdef
  target-tag: en1.2.3
# Only one of target-version, target-commit, target-tag of course.

then, a implementing a tool tracking changes should not be too complex.
Actually, I think referring to tags would be best but seems not supported with clickabe links by Github.
Btw. the version/release field in conf.py is currently unused.

Language setting:

www/docs/conf.py

Line 82 in d9fe5cd

language = 'en'

@Stolzenhain
Copy link

Wow, thanks for answering so fast – the separate metadata approach looks robust enough. Let's see, if I can pull off a pull request anytime soon.

@silopolis
Copy link

Hello friends,

May I ask what is the status of this more than two years after last post ?
I'd gladly initiate/participate in the French translation :)

TY
J

@sootynemm
Copy link

Hello friends,

May I ask what is the status of this more than two years after last post ? I'd gladly initiate/participate in the French translation :)

TY J

Likewise!

@silopolis
Copy link

silopolis commented Nov 11, 2022 via email

@sootynemm
Copy link

Le ven. 11 nov. 2022 à 15:39, sootynemm @.***> a écrit :
Likewise!
Meaning French ?

Yes, although I am not francophone, I can work with a native French speaker in collaboration if that helps. Pour le vérifier après, c'est tout :)

@silopolis
Copy link

silopolis commented Nov 11, 2022 via email

@plaindocs
Copy link
Contributor

Hi folks. This never got off the ground in the previous incarnation.

If anyone is familiar enough with translation sphinx to get a branch started I'll do what I can to get it merged. Definitely avoid anything in conf/* though.

@sootynemm
Copy link

as a former translator just learning to code, is there anything... easier to comprehend... than this documentation here? translation is hard enough as it is, but i have no idea where to locate the pootle: https://www.sphinx-doc.org/en/master/usage/advanced/intl.html#quick-guide

@plaindocs
Copy link
Contributor

heh, sorry about that @sootynemm - I don't have a bunch of experience with that either. I'm trying to get the Call for Proposals launched, but I'll try to have a look after that.

I think this is where you want to be looking

@Stolzenhain
Copy link

easier to comprehend

You're right – starting the actual translation is more important than perfecting a setup currently.

That's why I proposed placing the file anywhere as a starting point, create a pull request and make up the config later on. I never got to it though, sorry.

@sootynemm
Copy link

totally. well, i'll see what i can tackle this weekend i suppose! thanks :)

@Stolzenhain
Copy link

gave it a try, see #1849

@sootynemm
Copy link

see https://github.com/sootynemm/writethedocs_guide_fr/tree/main/docs/guide

this is the first pass of the french prose;

we could set up a kanban with any francophone volunteers that wanna compare the translation with the source and edit where they see fit;

not sure what localization protocol would be preferred for URLs so leaving as-is for now;

@silopolis
Copy link

silopolis commented Nov 20, 2022 via email

@Stolzenhain
Copy link

Nevertheless, I think this may be going too fast and that we should first select a toolchain and put it in place before taking the risk of wasting to much energy, and building a maintenance and synchronization nightmare.
[…]
as-is for now;
This is also among the questions that should be answered beforehand if it has the potential to badly impact accumulated translation work later.

Hello – seeing that this has been lingering for some time, I'd support @janbrohl 's comment:

I would suggest creating technically separate folders or branches with a conf.py each and link via Intersphinx. This would also enable us using localized paths/filenames.
[…]
For the separated approach: If the different versions don't need to be very direct translations we would see some natural drift needing a bit of synchronization work but offering more freedom for improvements.
I don't know of any existing solutions to this tracking-problem but an option for tracking would be to add a file for each translation (eg. translation-targets.yml) stating which page aims for which version […] then, implementing a tool tracking changes should not be too complex.

Which strikes me as sensible.

My question: Are these the next steps? Who would take on one of them?

  • including the intersphinx module in a translation branch
  • agreeing on a folder structure
  • agreeing on a config structure
  • running test builds against the new structure
  • and probably targeting the translating branch/tag w/ our pull requests

@plaindocs
Copy link
Contributor

Hey folks,

Thanks for looking into this, and getting started!

We really do need some tooling behind this, otherwise there is no way of knowing what changes when the English page changes, which will be no fun for everyone.

It would be great if someone who has run translation with sphinx-intl before could look at this, and see what the technical side is. But if nobody else jumps on that I'll have a look "within some timeframe".

@silopolis
Copy link

silopolis commented Nov 21, 2022 via email •
edited
Loading

@silopolis silopolis mentioned this issue Nov 22, 2022
Closed
@Stolzenhain Stolzenhain mentioned this issue Jan 5, 2023
Open
@silopolis
Copy link

Hi,

First things first, best wishes to yall for the coming year. May yall be healthy and safe :)

Sorry guys, end of year was a mess (aren't they all ?!) :/
I may be able to bend over this in the next days...

@sootynemm
Copy link

Happy new year. Let me know if I can pitch in in any way, even just as a fresh pair of eyes!

@silopolis
Copy link

Thanks, it will certainly be of great help!
I'll fork and create a branch for this with a PR linked to this issue.

One thing that may be nice to discuss the target translation platform. Proposed contenders would be:

All three have free hosted plans for Open Source projects.
Once sphinx-intl is configured and POT files generated, test setups could be configured to support platform choice...

@Stolzenhain
Copy link

One thing that may be nice to discuss the target translation platform.

I understood that due to the few updates one wouldn't aim for update-sensitive variants but simply a mirrored folder structure w/ a separate config.
Seeing that few of the pages receive update commits, one could simply check the file history diff.

As for grammar comments / corrections, couldn't these be continued to be handled in pull requests?

[Edit:] Looks like I misunderstood the package approach as I don't get why one would need a POT-based workflow here.

@silopolis
Copy link

Number of updates is one thing, number of languages is another. Translation platforms offer nice, featured and user friendly UIs to translators, whatever their technical level.
Having the luck of being a Sphinx-based project with built-in support for translation and not using it would be a pity.
Further, considering the purpose of the project, not using the best tool and practice for the job wouldn't make sense.

At least, I know that for French I'll use sphinx-intl and one of the platforms above, even if it to push translated files here in the end...

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
6 participants
@plaindocs @silopolis @janbrohl @Stolzenhain @howiezhao @sootynemm