Add Localisation Support With Fluent

[XAMPPRocky]

This PR adds support in the HTML renderer to localise fluent mdbook projects. It does this by adding a handlebars preprocessing step to the content, chapter title, and book title that allows it use a handlebars fluent plugin. This is a minimal version that people should be able to test. I would love to get feedback on adding testing in mdbook for localising and using the handlebars interface/API.

Localisation User Story

• The user writes their mdbook.
• The user later wants to localise the project.
• The user enables multilingual, which enables fluent localisation.
• The user creates a locales directory, either by marking a directory with that name, or specifying a directory with the locales config variable. Every fluent file in a subdirectory within the locales directory who's name matches a valid [Unicode Language Identifier][uni] is loaded into fluent.
• User replaces their previously inline strings in src with {{fluent}} helpers.
• A page for all languages (or just languages specified in languages-available) are localised through the fluent helper in handlebars and generated into markdown. Which is then rendered with the theme as HTML.
  • A version of each page is generated for each language even when there is no current differences between the file across localisations.
  • Other assets are still generated once.
• All locales except the default (specified by language in the book.toml, which is generated at the regular path) are generated under a folder matching their identifier.
• In the UI the user has select input of the locales in the top right.

Breaking Changes

• Right now the LinkPreprocessor is using its own custom parser and preprocessing step. This means that right now you have to pass helpers through {{{{raw}}}} handlebars blocks to be picked up. If this change is accepted, the LinkPreprocessor could be migrated over to work as a handlebars helper directly to avoid this.

Future Work

• This PR is limited only to the HTML backend, but really there is no reason this logic abstracted and extracted to work for any backend. However that requires additional design and implementation work around how to pass localisation data to different backends.

closes #5

[Manishearth]

Hmm, I'm not sure if this is the right path for translating books. I18n frameworks is great when you have a lot of formatting and some text, less so for books which are all text.

No harm in merging, but I feel that the right path here is typically to translate the entire book as a new book.

[XAMPPRocky]

No harm in merging, but I feel that the right path here is typically to translate the entire book as a new book.

I don't disagree with this idea, but I don't think it entirely applies to mdbook as mdbook doesn't solely generate books. I would assume people primarily consume the web based version of mdbook projects, which currently has no way to provide alternative localisations without as you said having to host completely separate versions, which on the brings in another category of problems around maintenance and discoverability of those localisations.

There's no obviously correct solution to this problem, but this PR provides a great solution with relatively minimal changes (The commit implementing it is ~350 lines) for the most popular backend, and it also doesn't prevent anyone from continuing to keep separate books if that's the workflow that's what works best for them.

[Manishearth]

Right, but it seems like it might be better to add more support for compiling a locales folder of books?

[XAMPPRocky]

I did think about that, and I initially tried to write the fluent implementation essentially like that, as I wanted to make it renderer independent. My impression (maybe someone who's more familiar with the code will disagree) was that it would be a lot of work to refactor the existing codebase around that, as you're essentially adding a whole new step (probably to the beginning) of the mdbook compilation lifecycle, this PR side-steps that by being an implementation detail of the very last step of one specific backend.

Adding that step would definitely be more than I could contribute currently. Even if this implementation was completed, there are UI/UX concerns around how to present the localisation to the user on the web. If for example different books weren't required to share the same to share the same SUMMARY.md then you couldn't automatically have individual pages link to their localised equivalents on the web, which can be a worse user experience.

[NICEXAI]

I like this PR.
I need i18n.
It's too much trouble to maintain separate documents for multiple languages.