Support Multiple Translations of Documentation

[0xTim]

Feature Name

Localised Documentation

Description

With the recent inclusion of multi-target support, one of the last big remaining features to allow Vapor to fully migrate over to DocC is localisation/translation support. Vapor's documentation currently supports 10 languages (either partial or full translations) in a seamless way. We'd really like to see localisation support added to DocC to support this.

Currently we use MKDocs to generate our documentation, with the mkdocs-static-i18n plugin. This allows us to provide different versions of our documentation pages with an ISO_639-1 suffix for each translation. E.g.

./docs_suffix_structure
├── assets
│   └── image_non_localized.png
├── image.en.png
├── image.fr.png
├── index.fr.md
├── index.en.md
├── topic1
│   ├── index.en.md
│   └── index.fr.md
└── topic2
    └── index.en.md

If a translation for the file does not exist it falls back to the default. This makes it simple to translate large documentation bundles piece by piece, rather than needing to do it in one giant go. I think something similar for DocC would be great, I haven't come across a better system yet.

As well as the extra files, we'd need to pass some configuration to DocC to tell it the languages we support and it would need a way of switching languages (and probably provide a switcher in the menu bar).

I'm aware that this is a huge piece of work and not expecting it to be implemented at any point soon but I thought it would be worth raising now for discussions!

Motivation

Not everyone speaks English, being able to add support for multiple languages opens packages up to more people.

Importance

Similar to motivation - this is an important long term feature to enable developers to write better documentation that supports a wider audience.

Alternatives Considered

Duplicated documentation, extra repos, another documentation system. None fit cleanly in