Asdf: Docs translation

[juliofortunato]

Hey there!
I'm interested in translating the new docs site. How can I do that?

[jthegedus]

Hi @juliofortunato I'd love to get this translated to many languages! :tada:

I've still got to update the contribution guide to make this more thorough, but the gist is this:

Docsify supports multiple languages so it's pretty easy. The configuration to support multiple languages goes in the docs/index.html file and then routes to the correct .md file.

Take a look at - https://docsify.js.org/#/configuration?id=coverpage

Now I'd like to support languages as the Docsify documentation does with a dropdown selection, however they are using a repo per translation, which I don't wish to do. What I would like is to have each language have it's own folder under docs/ but haven't tested this out as of yet (though I think it should work).

Since we are hosting on GitHub pages you can deploy it on your own fork by following the instructions here - https://docsify.js.org/#/deploy?id=github-pages

I will endeavor to update the contribution guides once we validate that the sub-folder approach works.

Feel free to share your progress of your attempts here :smile:

[juliofortunato]

Hey @jthegedus, sorry for taking so long.

I have translated all the docs pages but there are a couple of problems with Docsify I couldn't realize how to fix.

1. Translation works fine on local, but when deployed to GitHub Pages the sidebar does not change after selecting a different language. (You can check it here: https://juliofortunato.github.io/asdf)
   Note that coverpage changes for the translated version, but all the rest not.

2. For some reason, I always got 404 as homepage for the portuguese version.

Any ideia on how to fix these?

[jthegedus]

@juliofortunato Thanks for the work here, I will have the time available to investigate this tomorrow and will have some suggestions then!

[Stratus3D]

To link these two together, @juliofortunato created and then closed https://github.com/asdf-vm/asdf/pull/486 for this.

One thing I noticed @juliofortunato is that you used an emoji for the Brazil flag, and the english translation uses :uk::

  - [:uk: English](/)
  - [🇧🇷 Brazilian Portuguese](/pt-br/)

[juliofortunato]

@Stratus3D I opened that PR by mistake, my bad :sweat:

Regarding the emoji, I was not able to make the Brazilian flag to be rendered in any way. Neither:br:, :brazil: :flag-br: nor :flag_br: works.

[Stratus3D]

Yes you are right, I see a :uk: flag and a few others, but it apparently doesn't support a complete list of countries - https://jhildenbiddle.github.io/docsify-themeable/#/markdown?id=emoji

[juliofortunato]

I'm not sure what could be the best approach for this case :thinking:

[Stratus3D]

I'm not sure either. Did the emoji work for you or did it cause a problem? I would assume Docsify supports UTF8 and emojis, but I haven't checked.

[juliofortunato]

Yeah, it did work but it seems slightly smaller than the UK flag (check on the screenshot below). So maybe we could replace the UK flag (and all the future flags) for this version, in order to keep their appearance consistent.

Also, we have this Docsify plugin enabled, so I believe this should make emojis to work fine

[juliofortunato]

Also, any idea on how to fix the always-appearing 404 page and the sidebar on the translated version?

[jthegedus]

That emoji size issue is because of the docsify-emoji plugin. The HTML around the emoji is different depending on whether it is an inlined emoji (as with the br flag vs the uk flag). We could inline the :uk: flag as you have done with the br so it's the same.

Docsify's own site just delegates the different translations to their own repos, so not useful to study in our use unfortunately.

@juliofortunato Just looking at your fork now.

[jthegedus]

Alrighty, after some digging I have a few pieces of information.

1. the homepage.md file is built by using the Docsify embed feature to combine two .md files. Problem is, that feature is quote specific so is currently not showing anything. ~I will fix this in a new PR~ Done in https://github.com/asdf-vm/asdf/pull/490.

2. homepage: "homepage.md" Docsify implementation seems to be buggy.
   By default this field will load the file docs/README.md. Changing: docs/homepage.md to docs/README.md (done in https://github.com/asdf-vm/asdf/pull/492)
   docs/pt-br/homepage.md to docs/pt-br/README.md
   seems to fix the problem as the default setting is not buggy. This solves the 404 showing on the root route.

3. the Docsify nameLink feature is bugged at this time, so the asdf-vm header in the sidebar will always link to the English version regardless or the settings.

Docsify is currently looking for a maintainer, which someone has volunteered, but we are still waiting for the owner to assign permissions. This is why there are so many outstanding bugs not being addressed. I am in that discussion so will keep up to date with it's status and contribute fixes to the bugs that affect us.