[ WIP ] Support multi-language doc

[rllola]

See https://github.com/HelloZeroNet/Documentation/issues/113

• [x] Added icon in nav bar
• [x] Make it a dropdown with all the language
• [x] Add Translation HowTo
• [x] Script to generate all the docs in all the language
• ~[ ] Mobile compatible~

[anoadragon453]

Good start! Does the search field still work correctly after being moved?

[rllola]

Good start! Does the search field still work correctly after being moved?

Weirdly it does not. I didn't expect it to be affected by the new icon. I am gonna fix it.

EDIT: False alarm. My bad. I tested without the server running...

[rllola]

Update button with the dropdown menu.

[anoadragon453]

Looks good. Have you tested this on mobile layout yet by the way?

[rllola]

Looks good. Have you tested this on mobile layout yet by the way?

Yes. The layout is modified on mobile so a special css will be needed unfortunately. I will try to finish for next week.

[anoadragon453]

Ok, looking forward to seeing it!

[rllola]

@anoadragon453 Do you know how the doc is being deployed ? Do you do a mkdocs build and serve the files through apache or something ?

[rllola]

French translation + Translation HowTo button.

[anoadragon453]

@rllola This is indeed what I do.

Looking good :)

[rllola]

@rllola This is indeed what I do.

Could you share the config file with me ? Or is it ok if I put in an Nginx docker container ?

I see two things which need to be done in the config for it to work :

• docs/ and docs/en should both point to the english doc inside site
• docs/fr should point to site-fr which contain the french doc

And we should be good.

EDIT: Actually, I might misunderstood how the site is generated and we might event do better... :smirk: Will come with more about that tomorrow.

[rllola]

Ok I have made it. See the Nginx file with the 2 needed rules. Not sure how to translate it into Apache...

I still need to customize the generate.py because some folders has to move. But we are on the good path. I am pretty happy with it.

I removed the mobile compatibility from the list for this PR. I will do it in another one. This one already start to be heavy.

[rllola]

Done !

This is ready for review !

[HelloZeroNet]

thanks for the PR, here is a test deployment: https://zeronet.io/docs-dev/

Some things I noticed:

• The language changer leads to /en, /fr
• Displaying the current language (fr/en) next to the language changer icon would help what is that
• Probably we should use the same icon on the frontpage and on the docs next to the language change
• If we are in faq and we change the language it should lead to the same page but with the different language
• Adding cursor: hand to the changer dropdown could indicate what is that

[rllola]

• [x] The language changer leads to /en, /fr
• [x] Displaying the current language (fr/en) next to the language changer icon would help what is that Probably we should use the same icon on the frontpage and on the docs next to the language change
• [x] If we are in faq and we change the language it should lead to the same page but with the different language
• [x] Adding cursor: hand to the changer dropdown could indicate what is that

I believe that using the same icon is better. Consistency is good in general. I have done 3 screenshots of what it look like with different variants. Let me know which one you prefer.

[anoadragon453]

I definitely prefer the first one as it indicates action can be made, along with the current language it is set to.

[rllola]

I agree this is also my favorite. I modified the code to this one.

[HelloZeroNet]

Thanks, I have updated the source: https://zeronet.io/docs-dev/

Looks good to me, the only problem is with the search that is uses index from english docs and the links points to /en/ page

[rllola]

@HelloZeroNet Look like you have a rule that automatically redirect toward english. It forbid me to get the correct french file with this rule :

  # NEEDED !
  location /search/ {
    # Try to know the current language in order to send the proper serch_index.json file
    if ($http_referer ~ /fr/) {
      rewrite (.*) /fr/$1;
    }

    if ($http_referer ~ /en/) {
      rewrite (.*) /en/$1;
    }
  }

Could you show me your apache config file ?

[HelloZeroNet]

Actually I using apache, so I created separate rules and if it's possible I would not trust the referrer as it's not avaliable in every browser. Do you think if there is other way to do it?

[rllola]

Ok. No problem.

The search_index.json is loaded in application.js (https://github.com/squidfunk/mkdocs-material/blob/master/src/assets/javascripts/application.js#L290) which is part of the mkdocs-material sources. I don't think we can override it in theme like I did for the header.

The referer part was a bit hacky but the other solution would be a PR in mkdocs-material project.

However I am not sure what exactly ${config.url.base}/$ does... I am going to investigate otherwise I think we can do a PR to avoid the referrer hack.

[rllola]

@HelloZeroNet

I was actually able to override the javascript file and add it to the base.html theme file. It append the language suffix. Still hacky but better than the nginx rules I think.

[HelloZeroNet]

I was hoping it's easier to fix it, I have updated the source: https://zeronet.io/docs-dev/en/

There is some assets that is missing, because it's got accessed from /docs-dev/en/ dir

[rllola]

Some files are being redirected... Any reason that would be happening ?

The assets files should be outside of the /en directory.

EDIT: Or are those path redirected because they are missing ?

[rllola]

I have commited the generated site. You could directly serve it.

[HelloZeroNet]

It redirects all non-existent files to /en/ directory

It tries to load "modernizr.20ef595d.js", but in that directory it puts "modernizr.1aa3b519.js"

It works with the generated site, but I think it would be better not putting it to the repository and if the generated site is broken for me, then it's probably will be broken for others

[rllola]

Maybe you don't have the same version of mkdocs-material as me ? I have 3.1.0

$ pip list
mkdocs                        1.0.4    
mkdocs-material               3.1.0   

It look like he released a new version just before I start to work on this and it shipped differents files with it.

[HelloZeroNet]

Yeah, different version here:

$ pip list | grep mkdocs
mkdocs (1.0.4)
mkdocs-material (3.0.4)

I can update to 3.1.0, but this means that probably it won't work with the future versions.

[rllola]

We just need to be all using the same version and be careful when a new one is out to update base.html but it should work without problem.

If we freeze the dependencies in a requirements.txt file it should be fine.

[HelloZeroNet]

A took a step back and went using a different approach that does not requires modification of the base template or extra web server rules:

• Moved shared images/js/css files to docs/resources
• Modified docs dir to docs/en and docs/fr
• Modified site dir to site/fr in mkdocs-fr.yml
• Added docs/resources as custom_dir

Then built using mkdocs build -f mkdocs.yml and mkdocs build -f mkdocs-fr.yml

This way the en docs is at https://zeronet.io/docs/, the fr is at https://zeronet.io/docs/fr and the search is working. The img, js, css resources are duplicated, but I think this is the best solution we have now.

The lang changer menu is still missing can you please open a new PR for it?

[rllola]

It does work and I agree it avoid changing the base.html. However it does break the language menu.

Before that I would just replace whatever language code is in the url but now I would need to know the prefix path to it...

EDIT: I am actually not sure it is the best solution. As it does make it a little bit more complicated for the menu language to work. However I am fine with whatever solution works. Also I override the headers.html too so it might broke in the future too. Only if something with headers.html has been modfied tho and it is written in the documentation that you can override those so it will probably not happen actually...