search

cc-tweaked / CC-Tweaked

Just another ComputerCraft fork
https://tweaked.cc
933 stars 211 forks source link

Add multi-language support for wiki #1610

Open HfSrJun opened 1 year ago

HfSrJun commented 1 year ago

I think it would be useful if you add multi-language pages for official wiki, just like OC does (although its translation is far from finish). Many players from non-English countries are playing CC, as its useful for automation. But the English wiki is still a difficulty for most players. Maybe a local language wiki will decrease the difficulty for players. I can participate in translation for zh_cn language, like I had already done for some mods, like TIS-3D and Advanced Peripherals.

SquidDev commented 1 year ago

This is has been something I've been thinking about for a while, especially as part of #909 - if we ever embed documentation in game, ideally we'd support translations too.

My main concern here is about how to keep the translated documentation in-sync/up-to-date with the current code. Having translated documentation is definitely a good thing, and lowers the barrier of entry to using the mod, there is a risk that it's just unmaintained, at which point it becomes much less useful.

I think what I'd recommend for now is forking the mod and then translating the comments in-place. The workflow for publishing the docs is pretty simple, so you could set up a translated copy of the site - I'd definitely be happy to link to that from the README.

Long-term, it would be nice to reduce the friction of this, but I'm not quite sure how - most tooling for extracting documentation from code comments don't support translations, so there's not much prior art here. Python is probably the main language I'm aware of that translates their documentation - looking at their Spanish translation, it seems like they just extract the docs to a gettext file, translate that, and then stitch it back together, which I guess makes sense. Right now, that's quite a lot of tooling to build, so I don't think it makes sense to do until it's worth it.

HfSrJun commented 1 year ago

If an in-game manual is added it would be best, just like OC did (but its manual does not include everything, such as APIs). some mods use pachouli's book for their manual, and I had translated several. I think it's not ideal to use pachouli for very long documents, as its pages are small, and .json files are inconvenient to edit. I think a markdown reader like OC and TIS-3D used is great, although it has its own problem (start new lines incorrectly when showing Chinese). The outdated translation has always been a big problem, as translations are highly relay on communities(like https://github.com/CFPAOrg/Minecraft-Mod-Language-Package, a mod that maintain zh_cn translations).Actually, the reason why I (re)tranlated TIS-3D is the original one was seriously outdated and in bad quality, lol. As for fork and modify a new mod, I know barely nothing for Minecraft modding (what a shame). But I will ask someone with experience for help when I have time.

SquidDev commented 1 year ago

I think it's not ideal to use pachouli for very long documents, as its pages are small, and .json files are inconvenient to edit.

Yeah, I'd probably end up implementing my own version. I'm still very much in the planning stages here - finding a system which works well for CC:T's documentation and that external peripheral mods can hook into is tricky.

As far as editing goes, we use Weblate for doing translations right now, which is at least better than manually fiddling with the JSON. But not sure if it scale very well to long-form text. It might be possible to do it live in the site (for instance with tolgee), maybe something for me to fiddle with!

As for fork and modify a new mod,

Oh, to clarify, I'm not proposing you should have to maintain the mod! The trouble is right now all the docs are stored in-line with the source, and so the easiest way to translate everything is just to edit the code.

There are some docs on how to generate the docs, but I realise it's a bit of a mess, so happy to help in any way!

HfSrJun commented 1 year ago

I think it's not ideal to use pachouli for very long documents, as its pages are small, and .json files are inconvenient to edit.

Yeah, I'd probably end up implementing my own version. I'm still very much in the planning stages here - finding a system which works well for CC:T's documentation and that external peripheral mods can hook into is tricky.

As far as editing goes, we use Weblate for doing translations right now, which is at least better than manually fiddling with the JSON. But not sure if it scale very well to long-form text. It might be possible to do it live in the site (for instance with tolgee), maybe something for me to fiddle with!

As for fork and modify a new mod,

Oh, to clarify, I'm not proposing you should have to maintain the mod! The trouble is right now all the docs are stored in-line with the source, and so the easiest way to translate everything is just to edit the code.

There are some docs on how to generate the docs, but I realise it's a bit of a mess, so happy to help in any way!

I'm very surprised to see the zh_cn translation is far from complete, I thought a popular mod like this should have an up-to date translation, and I hadn't seen any incomplete string in game. so maybe I should complete the translation first.

mitomon commented 4 months ago

I think it's not ideal to use pachouli for very long documents, as its pages are small, and .json files are inconvenient to edit.

Yeah, I'd probably end up implementing my own version. I'm still very much in the planning stages here - finding a system which works well for CC:T's documentation and that external peripheral mods can hook into is tricky.

As far as editing goes, we use Weblate for doing translations right now, which is at least better than manually fiddling with the JSON. But not sure if it scale very well to long-form text. It might be possible to do it live in the site (for instance with tolgee), maybe something for me to fiddle with!

As for fork and modify a new mod,

Oh, to clarify, I'm not proposing you should have to maintain the mod! The trouble is right now all the docs are stored in-line with the source, and so the easiest way to translate everything is just to edit the code.

There are some docs on how to generate the docs, but I realise it's a bit of a mess, so happy to help in any way!

Howdy! Has there been any change to this or is modifying the code directly and self-hosting still the only way to add a translation? Also, are there any live examples of any sites?

tehgreatdoge commented 4 months ago

Perhaps a custom javadoc annotation could be used to specify a translation key for the docs sections? That way the code still has inline documentation but there is also an option for allowing translations that match up with the source?

SquidDev commented 4 months ago

Has there been any change to this or is modifying the code directly and self-hosting still the only way to add a translation?

No, afraid not. I don't think this is likely to change — I think my main concern from https://github.com/cc-tweaked/CC-Tweaked/issues/1610#issuecomment-1760380625 still stands, in that I don't think any such translations are likely to be maintained long term.

zyxkad commented 4 months ago

that's true, but how about use machine translation when they are not going to maintain anymore?