Added i18n + Spanish Localizations + Changes and Features

[Vexot]

i18n

I really like how Fusion is made, so I wanted to help it reach a bigger audience, that’s why I decided to add i18n (Internationalization) to the docs so everyone (kind of) no matter what language they spoke could learn more about Fusion.

Using the mkdocs-static-i18n plugin, it was just a matter of some lines of code to add support for localizations! But what if someone else wanted to contribute to the localizations as well? That’s why I made a guide which describes the process of adding a new language and localizing the docs in a proper way. I thought it would be good to have a section in which there are guides to learn how to contribute to Fusion docs, code, and localizations inside the repo (on a folder) or on the website (could be on extras page).

The only downside of this is the file organization, because most of the doc’s files were duplicated.

Spanish Localizations

Adding support for i18n wasn’t the only thing I wanted to help with, since I added i18n why not add localizations? As a native Spanish speaker that has been learning English since a very young age, I tried to make the most suitable and clean localizations for the docs with my previous experience localizing projects. The localizations were reviewed and quality assured by other translators with experience on the field.

Changes and Features

Here are some of the things that were changed or added:

• Added Twemojis using the markdown extension
• Added a localization guide at contribute/localization-guide.md
• Added embed support using OpenGraph and Twitter Card
• Moved index.js file to the index.md file so the navbar effect could work with i18n

Please, feel free to make any changes (and I apologize for the mess of commits). 🎉

[dphfox]

Wow - thanks for the interest! I really like a lot of what you've done here, and hugely appreciate the effort you've gone to.

However, I'm not sure if right now is the right time to start introducing localised content to the docs - after all, they're still incomplete and in flux! Lots of tutorials are stubs or haven't been written yet, some have issues with clarity, conciseness or bugs, and there may even still be larger structural issues with the way that topics are organised and presented. I would argue that, at least at this early stage, it wouldn't be worth adding localisation to the official documentation quite yet - it's far too important that it's up to date and understandable, and having to maintain localised versions adds a lot to that overhead - something we really don't want for a v0.1 product where documentation isn't finalised. For that reason, I'll close this PR for now.

That being said, I fully support this effort - I would love to see Fusion's documentation translated for different locales! With that in mind, I'll open an issue where we can keep on top of this stuff. What I would recommend in the meantime is to contribute to other non-English resources for learning and documenting Fusion, whether that be written tutorials, videos, or example places. These unofficial resources help to serve the same purpose of serving people from around the world, with the only caveat potentially being that it's not the official source of truth, and so isn't subject to the same level of review as it may be if it were part of the official Fusion project. If you're willing and able to maintain it, I may suggest hosting these Spanish docs on your own github.io website for the time being, so we can get this out to people at least. I would definitely consider linking to it for the benefit of our Spanish users while we work on finishing up these docs ready for a more final translation and localisation pass.

So, to tl;dr - love this work, but I'd prefer to save this until the docs are in a more final place where we can be more confident sweeping changes won't happen.

• Moved index.js file to the index.md file so the navbar effect could work with i18n

This actually introduces a nasty side effect - the contents of the script will become indexed and will show up in search results. This is the original reason it was moved out to a different file.

The proper solution here would be to use a custom template for the home page (I believe?) but I don't have enough experience with material-mkdocs to say for certain.

• Added Twemojis using the markdown extension
• Added embed support using OpenGraph and Twitter Card

I would prefer that pull requests stick to the Single Responsibility principle if possible - focusing on one change (internationalisation), rather than becoming a collection of small, unrelated changes. By splitting up related changes into their own PRs, it's much easier to evaluate these PRs on their own, and approve and deny them individually based on what we want to include and what we don't choose to pursue further.