Docs translation contribution in plan?

[moong23]

Hello
I'd like to contribute to your document by translating it into Korean if possible.
Any plan opening contributions as translating?

[ibgreen]

That would be really neat. We are using docusaurus which has some support for multiple languages that could perhaps be used https://docusaurus.io/docs/i18n/introduction

[moong23]

Cool 👍 Please let me know how I could start translating the docs when u r ready

[ibgreen]

That looks great, very exciting! I had some discussion with maintainers and there was some hesitation since deck.gl has a lot of documentation and it was unclear how much you can commit to this. If you build a translation in a separate repo that will enable to you come back with a more powerful proposal.

[moong23]

Sure! Sounds great.
Actually I've already started translating a day before your proposal.
It's only one Readme file translated but you can check it on my repository i've forked.
https://github.com/moong23/deck.gl.kr
feel free to ask any details if needed 👍

[moong23]

translated 2 docs which are

• README.md (on the root directory)
• docs/README.md
  so far. Feel free to checkout.
  Since I'm not really translator, it might be hard to translate all the docs shortly but I'll try to translate at least one docs a day :)

[donmccurdy]

In case it is helpful — do feel free to ignore it if not! — here is a proposal I wrote up last year for reducing the workload involved in three.js's translated API documentation. Only Milestone 3 really applies to deckgl:

https://gist.github.com/donmccurdy/db75b86a28a775135e33317ce2694a32#milestone-3-generate-translated-api-documentation

In the case of three.js we hit a blocker: TypeScript does not support much JSDoc syntax. But that would not be an issue for Deck, written in TypeScript which is fully supported. The main intent was to have a CSV (or similarly 'queryable' document) making it easy to identify which translations are missing for a given string and language, and which translations are older than the current English text. The original English strings would be extracted from JSDoc or TSDoc in source files, with a unique key like "TileLayer#constructor".

Similar to the hesitation @ibgreen mentioned above, we've found it challenging to keep full-length hand written API documentation pages in sync with changes to the API itself and to translations. See mrdoob/three.js#24984.

[ibgreen]

Moving from current manual docs to a JSDoc auto-generation variant would be a very significant step - someone would need to be willing to put a lot of effort into championing and executing this. Ultimately, it may need to cover all our repos, on the principle that having different setups creates too high a barrier for contributors and maintainers.

Alternatively, how about we make a plugin for docusaurus to show on each page the date the underlying markdown page was modified. Then users can quickly switch between translations (I assume there will be a dropdown in the header) and check how fresh the page is.

Or we can simply require each markdown page to mention at the top or bottom what version it was last updated for?

[donmccurdy]

Agreed that it's a large change and would require one (if not more) highly-engaged contributors. So I agree with your assessment that the translation probably should not occur in this repository without a strong proposal and contributors, and that it'd make sense for the approach to be proven first another repository.

I meant the RFC above as ideas for how the separate repository could manage things, if it helps contributors, not a proposal (at this time) for this repository. From that perspective – a plugin showing the date on the page would be good, showing the dates for all files in a CSV or JSON file might be even better, but I'll defer to any potential contributors on that.

[ibgreen]

Yes it would probably not be hard to make a script that collected that information in a CSV and perhaps also generate a list of outdated pages for each translation.

[ibgreen]

Maybe even run git diff on the english version and show changed text fragments?

[grahambates-code]

My gut feel is that adding translations could hinder more than help, its hard enough keeping one set of docs up to date, could be painful having to wait for translations for other languages to be complete before pushing out a new version?

Automatic translators seem very good now, and hyper links can be added to translate a page, eg Korean