Docs: translate introductory content

[agjohnson]

In the past, we've discussed what portion of our documentation it would make sense to keep translated. While full translation would fantastic, it would also be optimistic given limited resources.

Where we landed was to focus on introductory content first, and work from there. This benefits new users and new developers the most, as it removes the upfront need to understand English or machine translated English. New users and new developers already have a lot to learn.

The locales we see most commonly: [zh_CN, ru, fr, ja, es, pt_BR, de]

[silopolis]

install, getting_started, localization, support and api--doc_builder have the highest priority in Transifex. Maybe these could, at least, be translated waiting for the Great Refactoring ?

All other resources are average priority, and only 4 are low priority. Most probably some should be promoted (architecture ?...), many demoted.

Overall, if refactoring is mainly a big restructuring, translated strings will be in TM and translators will only have to revalidate them.

[agjohnson]

Overall, if refactoring is mainly a big restructuring

It is both restructuring, but also rewriting a fair bit too. The first pass leans more towards restructuring and moving content, but we are also rewriting content to bring it up to new standards.

I'm not super familiar with how well Transifex will track moved content, but I'm guess it doesn't do this well.

Maybe these could, at least, be translated waiting for the Great Refactoring ?

The RTD and Sphinx guides might be safer. These are not going to be altered drastically yet and are quite large too, so it wouldn't hurt to get a head start.

[benjaoming]

We could potentially use sphinx_rtd_theme docs as a prototype to see how we can translate a subset of an English documentation to another language? I believe that the entire "demo" could be left out of translation, same with the "Changelog". If we can make a smaller setup work here, then we could scale up and replicate the workflow in Read the Docs' user docs.

[benjaoming]

The RTD and Sphinx guides might be safer. These are not going to be altered drastically yet and are quite large too, so it wouldn't hurt to get a head start.

I think we need to be a bit careful that we don't make a tonnes of effort translating 10% of the documentation (it's still many many hours of work) and end up in exactly the same place. As with the Diátaxis refactoring, I think we should lay out a clear plan of where we want to end up. How should a French version look?

The design problem/challenge: Simply prioritizing a subset of pages is not enough. We need to find a solution that works for our documentation and for a particular language and some subset of pages that it contains. I'm afraid that a 10% translated version of the docs (with the other 90% in English) will look very very strange. I also don't like the idea of only exposing a French user to 10% of the documentation and hiding the other 90%, worst-case people end up not getting information that is present in English.

If we come up with something clever here, we will solve a design problem that is faced by all other translated documentation projects as well. I think it's very rare that a documentation project can afford to do 100% translations and keep them updated.

Our challenge is about the translation workflow, the documentation's navigation and allowing for a certain deviations in contents and structures.

[ericholscher]

I'm putting some notes from our latest call here, hopefully it doesn't conflict with the existing discussion. It basically lays out our high-level plan for this work:

Notes from our call:

High level status

☑️ Agreed on doing Tutorial content to start
☑️ Agreed on using gettext & transifex
☑️ Only show tutorial content on transifex to translate, to simplify the work
- ❓ How to implement this process on RTD
- ⚠️ English content can have a warning banner (/es/latest/api/ for example)

Next steps

v1: "Transifex is not lies" - We update translations regularly. We hide non-tutorial files in transfex to start, so that's the only content available for translating. Once a team has translated the tutorial content, we can discuss adding more to translate in that language.
v2: "Nice, published tutorial content" - Engage with translators around tutorial content, publish top-level es/fr with only-translated content in the TOC. Basically https://docs.readthedocs.io/es/stable/tutorial/ is a valid URL, and only has translated content in the sidebar TOC & accessible.

Timeline

I'm putting v1 of this work in our Q2 roadmap (April-June). We will see how things progress from there to better understand getting to v2.

[agjohnson]

I'm putting v1 of this work in our Q2 roadmap (April-June). We will see how things progress from there to better understand getting to v2.

That's a good timeframe, translations are still non-priority for us, so I don't want to get too far ahead.

I would also be +1 on manually updating the sources for the tutorial content as soon as we feel it's stable from refactoring, just to start this process early. We'd still need to automate this and would need to configure Transifex a bit.

[ericholscher]

It seems like this is unfortunately not something we're able to maintain in the long term, so I'm going to close this issue.