Offloading the Hosting and Maintenance of the Non-English Docs

[WestLangley]

I propose that the Non-English docs be hosted elsewhere -- and maintained by others.

Being responsible for ensuring the English and non-English docs remain in sync is not an efficient use of the three.js maintainers' time.

Furthermore, it is a burden that is only going to increase as more languages are supported and the docs become more complete.

This thread is for discussing how offloading the hosting and maintenance of the Non-English docs may best be accomplished.

It would be helpful if someone would be willing to take responsibility for this task. 😇

[takahirox]

+1 for this

Being responsible for ensuring the English and non-English docs remain in sync is not an efficient use of the three.js maintainers' time.

I agree with this. I have been feeling the same.

[Mugen87]

Being responsible for ensuring the English and non-English docs remain in sync

I think it's sufficient if we just state that the maintainers only manage the English docs from now on. In this way, we can still keep the other languages in the repository which makes it easier to overlook the translation process and host everything.

[Mugen87]

BTW: This discussion should also include the translations of the manual.

[WestLangley]

In this way, we can still keep the other languages in the repository.

No. That would be a poor decision from a management standpoint. The maintainers would then still be responsible for responding to bug reports and merge requests for the other languages.

[Mugen87]

The maintenance in that regard is minor. I have no problem to be personally responsible for this task.

[donmccurdy]

For a mature project like three.js, high-quality translations (or internationalization / "i18n") feel very important, and I'd be sorry for that area of the project to become stale. Really grateful for the folks doing these translations. If we simply offload translation to "the community" and don't set up a good workflow for keeping things in sync, then I expect the translations may degrade quickly. Our hands-off approach to @types/three will not suffice here.

With @Mugen87, I am glad to be involved in this task in any way. This is important to me.

It may be that the current setup is not that great for translators either, and offloading (done well) might actually improve things. For example, a separate repository might allow maintainers of the translations to set up tooling that we haven't provided here, for quickly identifying:

• new strings, not yet translated to language X
• updated strings, changed since translation to language X
• progress, % of documentation translated to language X

I'd love to hear from people doing these translations: What works today? What doesn't? How do you feel having translations occur in a separate repository, possibly with more dedicated tooling to support that? Are there tools for this you've used before, and liked?

[WestLangley]

I'd be sorry for that area of the project to become stale.

They are already stale.

[Mugen87]

The maintenance work I do is straightforward right now because when a single documentation page is updated, the changes can often be copy/pasted with an editor (new code example, updated signature etc.). But granted it is not a scalable solution to copy each documentation page and translate the contents by hand. However, using a real translation system with placeholders in the documentation templates and a language database seems out of scope.

I'm not an expert in this field but would it be possible to avoid any manual translation and just ask the developer to use a tool e.g. like Google Translate? Are the results considered to be good enough now?

I've tested this today with some guides from the documentation and the results are about right (at least when you translate into German). I mean the tool translates some words that it shouldn't (like render target) and the structure of a sentence is sometimes a bit weird but at least you understand the actual content of the article.

I wonder if there is a way to improve the English docs so a translation tool can produce better results. Like preventing the translation of certain words or defining their syntax (e.g. that "render targets" should not be translated and is the plural of "render target"). Maybe it would be possible to tweak the results up to a point where it can be considered as "good enough" and a manual translation isn't necessary anymore.

[donmccurdy]

However, using a real translation system with placeholders in the documentation templates and a language database seems out of scope.

I wish I knew a practical way to do this, but, yeah. I'm not sure we have the resources.

I wonder if there is a way to improve the English docs so a translation tool can produce better results

One option would be to change how we're using <code> blocks today. We use them for longform code blocks, but that's really what <pre><code> is for:

<pre><code>
import * as THREE from 'three';

...
</code></pre>

If we change that, we could start using <code/> for inline tokens instead, like:

<p>
  This guide explains how to use <code>GLTFLoader</code>.
</p>

Then we just need to prevent translation from affecting code tags, but limit syntax highlighting to <pre><code> blocks.

[Mugen87]

It seems doing this:

 <span translate="no">render target</span>

prevents Google Translate from translating the words into another language. I've tested this with Chrome and the built-in translating option. The translate attribute is not Google Translate specific so other tools should recognize it as well.

[Mugen87]

At least Google Translate does already not translate the code examples in the documentation. I guess this happens because the code blocks already have the translate="no" attribute set.

three.js/docs/page.js

Line 164 in 6663480

e.setAttribute( 'translate', 'no' );

[donmccurdy]

Yeah, it may be more practical to use <code /> blocks inline, and let the script add translate="no", rather than using a span with attributes each time.

[Mugen87]

Um, I'm just not sure if it's right to use the <code /> element like that. AFAIK, it's intended to define computer code in HTML files. We just want to mark specific text from not being processed by the translator. Sounds a bit like a misusage to me. To me, the<span> tag with an additional attribute feels like the cleaner approach.