amindWalker commented 1 year ago

# Dioxus Translated Documentation

Hi there, I'm building a Rust Knowledge Base Center and I'm using Rust for both backend and frontend.

I was using Yew.rs before I discovered about Dioxus 2 days ago while I was googling Yew's documentation... and I have to say, that was the best find of the day! Dioxus is so much more elegant than Yew imo. I'll build my frontend with Dioxus now!

I got really excited and I wanna help to spread the word and the fastest way for me right now is by translating (PT-BR in this case) all the documentation. I wish I could help with code but you know... I'm still learning Dioxus😅. But later, after enough hacking with Dioxus, I'm planning to help with examples and with code as well.

I don't know which Markdown files are used for the mdbooks so I decided to translate every one of them with relevant content in it.

I've forked the project to diff with my translated files. For every translated file I appended "_pt-br.md" for easy tracking.

I've made a progress table summary:

Repo Description README

Original	Brazilian Portuguese	Translated
README.md	README_pt-br.md	✔

Guide

Original	Brazilian Portuguese	Translated
final.md	final_pt-br.md	✔
hello_world.md	hello_world_pt-br.md	✔
README.md	README_pt-br.md	✔
ROADMAP.md	ROADMAP_pt-br.md	✔
setup.md	setup_pt-br.md	✔
SUMMARY.md	SUMMARY_pt-br.md	✔

Guide Section

Reference

Original	Brazilian Portuguese	Translated
README.md	README_pt-br.md	✔
SUMMARY.md	SUMMARY_pt-br.md	✔

Reference Section

Router

Original	Brazilian Portuguese	Translated
README.md	README_pt-br.md	✔
SUMMARY.md	SUMMARY_pt-br.md	✔

Router Section

My guess is that many like me came from React and TypeScript and if I can make this transition easier by translating everything that's fantastic.

I want to reduce the number of files to as minimum as possible so merging would be effortless. Where should I look for that?

Any suggestions/modifications for this being merged and a PT-BR section added in the Home Page/README.md?

Btw, thanks for this awesome tool!

rMazeiks commented 1 year ago

This is impressive work! Though I wonder if it would be best to keep translations in separate repositories... Otherwise it might be hard for the maintainers to keep the official docs up to date, and the codebase can get crowded (especially if more languages are added).

Also, as far as I can tell, Mdbook doesn't have multilingual support yet, so the most user-friendly option we have is probably deploying a separate book for each language (otherwise, how will the users navigate it?).

amindWalker commented 1 year ago

@rMazeiks Yeah, I asked myself the same question but I didn't find a solution, yet. So I did translate everything to leverage my excitement haha.

But I made a research and found a few options:

Wait for mdBook support multiple languages (don't know how long this would take)
Test translation crates on crates.io
Use docusaurus (probably that's what the fellows at Yew.rs are using but this approach would lose many benefits of the mdBook)
Merge translations into a single mdBook file as @rMazeiks suggested, one for the standard guide and one for the reference guide.

The last one seems the most doable right now, but I think the disadvantage would be losing the ability to diff each new commit to documentation adequately. Translation crates seems plausible but that's another crate to depend on.

I would definitely go for the last option if there is a green light for it. Later when mdBook adds multiple languages support I'll redo and review all translations again.

Suggestions, toughts?

rMazeiks commented 1 year ago

Wait for mdBook support multiple languages (don't know how long this would take)

The issue is from 2015, and the last comments (a month ago) seem to indicate that not much progress has been made. So I think self-driving cars will come first, and then i18n support for mdbook.

Use docusaurus (probably that's what the fellows at Yew.rs are using but this approach would lose many benefits of the mdBook)

The main benefits of mdBook I can think of are

Simplicity of MD (as opposed to a fully-fledged static site generator)
Wide adoption in Rust projects
Written in Rust (🚀🚀🚀🚀), not JS (🤮🤮)
Can test code snippets (though I don't think we're using this much)

Are there others? Though I personally prefer mdbook, it might indeed make sense to switch to something else to get i18n if these 4 are all we lose.

I would definitely go for the last option if there is a green light for it

Agreed, I'm curious to hear what the maintainers think.

It looks like there's already a separate website for Chinese docs (linked from the Chinese Readme), though there are some differences (look&feel, domain) – it might be nice to introduce some consistency.

amindWalker commented 1 year ago

I should add that - apart I'm translating to PT-BR - I'm trying to solve translations in general for every language so it's easier for everybody to do their own translation effort.

I could translate to other languages as well, but let's solve this first.

jkelleyrtp commented 1 year ago

Thank you so much for this! We've got some simple Chinese support but it hasn't been mainlined into Dioxus yet.

This is all community maintained (though the maintainer is a maintainer in the Dioxus project, it's not an official Dioxus project).

https://www.dioxus.cn

https://github.com/DioxusChina/website

My only concern is that as the docs evolve, our translations won't, and we'll need to somewhat frequently ping the original authors to get updates.

I think it would make a lot of sense to have a "translations" folder in our docs repo with different mdbooks for each language. The guide would be a bit different for each translation, but that's better than not being able to update the docs without coordinating a big effort among all the language maintainers.

There's another big docs pr open in #486 that would heavily conflict with this PR if we weren't careful with how we separated things out.

My proposal:

For the time being start a new folder and add our pt-br (and chn, later) translations
(later work) update CI to generate different flavors of the guide
(later work) attach the different flavors to the dioxuslabs.com site with a language switcher

Eventually I'd like to build our own mdbook/docusaurs library that handles both landing page generation and docs/guidebook generation, much in the same way that docusaurus works. I have many projects I'd like to build docusaurus books for but haven't really wanted to dip back too much in the JS ecosystem.

Edit: do you mind rebasing so the merge conflicts go away? #486 has been merged, so it would make sense to pull out all the pt-br docs into their own mdbook and then drop it in a translations folder. Alongside the overhaul of dioxuslabs.com, we'll make sure to feature it prominently on the main landing page, in the guide, and on github.

amindWalker commented 1 year ago

Hi @jkelleyrtp ... great! @rMazeiks made a nice work! I guess we're all in accordance with the approach of merging everything in one place should be easier or at least the best option for now. I took one step further and added additional features and some fixes:

Added a README section to PT-BR language in the original README.
Unrelated to docs files, like the README, can be placed in a translations folder in the project's root for easy access.
Added the ability to change the Documentation's language (an 🌎 icon in this case) now it's easier for everyone to add their own translations. The method consists in a custom build of a unmerged mdbook feature from this mdBook PR: https://github.com/rust-lang/mdBook/pull/1306

The translated content should be in a folder named pt-br, es, en, cn... that goes within the src folder of docs. A new section must be added to the book.toml file using this pattern: [language.cn] or [language.pt-br]. This will generate a book for each language in the output book folder. So if someone accidentally stumbles on Dioxus, like me 😆, and wants to translate to, let's say, Korean it would be necessary to just duplicate the en folder, rename it to kr and start translating.

I structured in this way trying to make it easier for newcomers (and current ones) to access and edit files. I tested some translation crates and IMO this was the easier way to solve translations for everybody.

I've found some errors related to the examples/*.rs mdBook's pre-process like this:

2022-07-07 19:43:41 [ERROR] (mdbook::preprocess::links): 
Error updating "{{#include ../../examples/anti_patterns.rs:iter_keys}}", 
Could not read file for link {{#include ../../examples/anti_patterns.rs:iter_keys}} (../../examples/anti_patterns.rs)

But the HTML documentation compiles just fine.

Unfortunately, I haven't found a workaround for the default language beside defining an en folder and [language.en] property as well, duplicating files in the process to make it work with mdbook build. Would it be bad if the default documentation lives within the en folder? And by consequence delete the other files outside their correspondent folder names?

The only question left is if this whole process applies to the router docs as well?

jkelleyrtp commented 1 year ago

Hi @jkelleyrtp ... great! @rMazeiks made a nice work! I guess we're all in accordance with the approach of merging everything in one place should be easier or at least the best option for now. I took one step further and added additional features and some fixes:

Added a README section to PT-BR language in the original README.

Unrelated to docs files, like the README, can be placed in a translations folder in the project's root for easy access.

Added the ability to change the Documentation's language (an 🌎 icon in this case) now it's easier for everyone to add their own translations. The method consists in a custom build of a unmerged mdbook feature from this mdBook PR: Add option to localize books in multiple languages rust-lang/mdBook#1306

The translated content should be in a folder named pt-br, es, en, cn... that goes within the src folder of docs. A new section must be added to the book.toml file using this pattern: [language.cn] or [language.pt-br]. This will generate a book for each language in the output book folder. So if someone accidentally stumbles on Dioxus, like me 😆, and wants to translate to, let's say, Korean it would be necessary to just duplicate the en folder, rename it to kr and start translating.

I structured in this way trying to make it easier for newcomers (and current ones) to access and edit files. I tested some translation crates and IMO this was the easier way to solve translations for everybody.

I've found some errors related to the examples/*.rs mdBook's pre-process like this:
2022-07-07 19:43:41 [ERROR] (mdbook::preprocess::links): 
Error updating "{{#include ../../examples/anti_patterns.rs:iter_keys}}", 
Could not read file for link {{#include ../../examples/anti_patterns.rs:iter_keys}} (../../examples/anti_patterns.rs)
But the HTML documentation compiles just fine.

Unfortunately, I haven't found a workaround for the default language beside defining an en folder and [language.en] property as well, duplicating files in the process to make it work with mdbook build. Would it be bad if the default documentation lives within the en folder? And by consequence delete the other files outside their correspondent folder names?

The only question left is if this whole process applies to the router docs as well?

Moving documentation to an "en" folder is completely fine. I think git might be smart enough to correlate the move so we won't lose history.

Don't worry about the router right now, its docs need updating before we should think about translating.

This is great! We can keep using that fork of mdBook for the forseeable future... IMO mdbook is basically "done" and just missing translation support, so using a fork is not a big deal.

amindWalker commented 1 year ago

Hi @jkelleyrtp ... great! @rMazeiks made a nice work! I guess we're all in accordance with the approach of merging everything in one place should be easier or at least the best option for now. I took one step further and added additional features and some fixes:

Added a README section to PT-BR language in the original README.

Unrelated to docs files, like the README, can be placed in a translations folder in the project's root for easy access.

Added the ability to change the Documentation's language (an earth_americas icon in this case) now it's easier for everyone to add their own translations. The method consists in a custom build of a unmerged mdbook feature from this mdBook PR: Add option to localize books in multiple languages rust-lang/mdBook#1306

The translated content should be in a folder named pt-br, es, en, cn... that goes within the src folder of docs. A new section must be added to the book.toml file using this pattern: [language.cn] or [language.pt-br]. This will generate a book for each language in the output book folder. So if someone accidentally stumbles on Dioxus, like me laughing, and wants to translate to, let's say, Korean it would be necessary to just duplicate the en folder, rename it to kr and start translating.

I structured in this way trying to make it easier for newcomers (and current ones) to access and edit files. I tested some translation crates and IMO this was the easier way to solve translations for everybody. I've found some errors related to the examples/*.rs mdBook's pre-process like this:
2022-07-07 19:43:41 [ERROR] (mdbook::preprocess::links): 
Error updating "{{#include ../../examples/anti_patterns.rs:iter_keys}}", 
Could not read file for link {{#include ../../examples/anti_patterns.rs:iter_keys}} (../../examples/anti_patterns.rs)
But the HTML documentation compiles just fine. Unfortunately, I haven't found a workaround for the default language beside defining an en folder and [language.en] property as well, duplicating files in the process to make it work with mdbook build. Would it be bad if the default documentation lives within the en folder? And by consequence delete the other files outside their correspondent folder names? The only question left is if this whole process applies to the router docs as well?
Moving documentation to an "en" folder is completely fine. I think git might be smart enough to correlate the move so we won't lose history.

Don't worry about the router right now, its docs need updating before we should think about translating.

This is great! We can keep using that fork of mdBook for the forseeable future... IMO mdbook is basically "done" and just missing translation support, so using a fork is not a big deal.

Perfect! I think the same about mdBook docs. It is indeed awesome, probably the best documentation tool I've ever used, it just needed this localization feature to be complete.

So I guess we're in good shape now. Marked as ready already.

jkelleyrtp commented 1 year ago

Hmmm, for whatever reason git did not pick up that the files were moved from src to en, so in this PR the docs have lost their commit history.

I made a PR that does the internationalization changes in a way that preserves the git history here:

https://github.com/DioxusLabs/dioxus/pull/494

I need to do a slight bit more tweaking, so you'll need to rebase on top of it (or git will figure it out automatically)

Edit: for your rebase, update the book.toml if you can and SUMMARY, index, and roadmap since those are duplicated. Edit Edit: I need to update the fork of mdbook to support included folders

amindWalker commented 1 year ago

Rebase done. I guess it's good to go, but let me know if I missed something and I'll gladly fix it.

amindWalker commented 1 year ago

Yeah, sure. I'm in for more on the long run, just need to get good at Dioxus first then I'll deep dive with Mobile+WebAssembly (my main interest in Dioxus) ✌

DioxusLabs / dioxus

Add PT-BR translations #456

Repo Description README

Guide

Reference

Router