How can I obtain the frontmatter of a document in other languages?

[rrousselGit]

Hello!

I'm trying to implement a feature request I made recently: https://docusaurus.io/feature-requests/p/add-optional-version-number-in-docs-metadata-to-help-maintain-translated-docs
(on that note, I have the user experience of that feature-request page pretty bad).

I've played a bit with slizzing components and ended-up sizzling DocVersionBanner and using useDoc() to obtain metadata about the current docs. So I was correctly able to obtain the frontmatter for the opened doc

But now I'd like to obtain the frontmatter of that same doc in other languages. And I haven't found a solution so far. Is there an API for this?

[slorber]

Hey, I understand the problem.

For sure it's hard for localized docs to stay in sync with the upstream language, particularly if done manually.

You can try using:

• A SaaS like Crowdin (upload source translations / translate through SaaS / download translations): the SaaS will ensure all languages have the same strings
• A strategy like ReactJS where each language is a fork that sync with upstream repo (described here: RFC: Docusaurus v2 i18n #3317)
• A more manual strategy like you are trying to use with doc version numbers

---

Something to explore: using git patches to patch localized folders with changes from the "upstream folder". I've had some success with that approach recently while trying to automate the backport of docs from the upstream version ./docs to older versions ./versioned_docs/2.1.0 (see #8036). It's not the same use-case but it remains quite similar IMHO.

This worked with this weird Git command:

git format-patch -k --stdout v2.0.1...slorber/docusaurus-v2.1-backport -- website/docs | sed 's,a/website/docs,a/website/versioned_docs/version-2.1.0,g ; s,b/website/docs,b/website/versioned_docs/version-2.1.0,g' | git am -3 -k

In human words: "take all recent docs changes diffs, and apply them to version 2.1.0 docs"

---

Otherwise if you really want to do your manual docs versioning strategy, be aware that Docusaurus does not read other localized files when building a site in a given locale. If your default locale is English and you build the site in French, it won't read the English docs file. What I mean is that by default if you build in French you can only access French frontmatter. Reading extra markdown files could slow down build times and won't be used by most sites.

However, we'd like to introduce a low-level createFrontMatter hook that could allow you to implement what you want: when creating the french frontmatter, you'd be able to enhance it by reading the frontmatter of 2 files (French + English).

This probably makes sense that we make your use-case convenient to implement by at least injecting the 2 file paths here (original doc path + localized doc path) so that you can easily read both files frontmatters and aggregate them.

In the end you could have something like frontMatter.my_custom_version + frontMatter.original.my_custom_version

Does it make sense?

(on that note, I have the user experience of that feature-request page pretty bad).

What do you mean, the embed iframe experience is bad? It's a std https://canny.io/ board that we didn't code ourselves.

[rrousselGit]

Thanks for the reply!

The createFrontMatter hook definitely sounds like something that could help, yes.

I kinda realized that Docusaurus does not bundle and allows different languages to interact with each other. Although for frontmatter specifically, it probably could be a reasonable exception – which seems to be what you're suggesting too.

---

In the end, I found a workaround to my problem, by using some form of metaprogramming.
I wrote a code-generation script that parses all the docs and generates a JSON of all the outdated translations.

Although this involves an extra build step and increases the difficulty of contributing. Now folks who update docs have to re-generate that JSON. But with some extra work, it could possibly be fixed by doing the generation before deployment.

---

I'm personally not sure about the alternatives.
What I like about this "version" variant is, it doesn't slow down writing new content in the original language. New content can be written without having to go through all transactions. And translations have all the time they want to sync with changes.

After all, since it's an OSS project, folks who work on translations do so in their free time. So contributions are a bit unreliable.

You could say that it's kind of voluntary that transactions get out of date.

---

About canny.io:
In comparison to plain Github issues/discussions, I feel like that site has a worse user experience.

For example, we can't write markdown in the post; the form for creating a new post is tiny, and finding posts you previously posted is difficult.
For reference, I spent a good 10 minutes looking for the feature request I made before to link it here.
I forgot what was the title of my request and didn't realize it was still on the front page. So I tried a bunch of keywords repeatedly but failed to find it.

With GitHub, I could do author:rrousselGit in the search bar and see all of my posts. Or I could sort by time posted / time updated / ...

[slorber]

I kinda realized that Docusaurus does not bundle and allows different languages to interact with each other. Although for frontmatter specifically, it probably could be a reasonable exception – which seems to be what you're suggesting too.

Yes, noted to support that use-case in the future

---

Note that if you use a SaaS like Crowdin translators do not have to translate content immediately. They'll be notified of new strings to translate, and in the meantime docs will be published up-to-date (unless you decide to block publish) but some content will be in both source+target language. That seems reasonable to me. See an example here: https://docusaurus.io/pt-BR/docs/blog#blog-post-date

Using git forks, it's painful to manage but you wouldn't have to sync the forks immediately, and you could keep publishing the old stale localized site until you are ready to sync/translate upstream changes.

---

Yes agree that Canny became probably less interesting, particularly since GitHub discussions can be upvoted and sorted by score too... will see if it's worth removing it later and what to do with the existing canny content