i18n should not assume 1-1 matching between translated locale routes

[yzeng25]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Motivation

Hi,

First of all I want to thank you all for providing such an awesome open-source tool. I've been using it for 2.5 years in different companies, Docusaurus has been stable and extremely easy to use and maintain.

I started using the i18n feature to implement multi-language blogs about half year ago. It works fine since then. But as our team grows and kind of diverges, we figure out that simply putting blogs in two languages is barely enough. Then we are discussing about publishing blogs in 2 languages, English and Chinese, separately.

So then I tried to verify the feasibility of this thought, and it kind of failed from several aspects.

Case 1: Publish an English blog only. Everything works well (i.e. yarn start local preview, online previews), except when clicking on the language switch button and redirects to the default 404 response page.

Case 2: Publish a Chinese blog only. This is where the nightmares come in. The yarn start -- --locale zh local preview works. But when generating online preview, this somewhat becomes a 'ghost page'. More specific, this page is unreachable by any means.

Then I went through Docusaurus's documents and learned some basic ideas about it. The i18n feature works when the 1-to-1 relationship is established for a blog in 2 languages, which totally makes sense in most cases. But when we need blogs only presented in one language, it partially failed.

So I am wondering if there is a work-around to this issue, or some kinds of feature flags/vars that I could use to avoid it? I know this is a very rare corner-case, and this might be too much to ask for, but could you consider fixing it in future releases?

Thanks,
Yilin

Self-service

• I'd be willing to do some initial work on this proposal myself.

[Josh-Cena]

Hi, I'm not too sure I understand. You have two blogs: Chinese and English, and they are generated using Docusaurus i18n, with English as base locale. Now, you want to publish them on different domains, so the language switcher doesn't work, correct?

[yzeng25]

Hi, I'm not too sure I understand. You have two blogs: Chinese and English, and they are generated using Docusaurus i18n, with English as base locale.

Yes.

Now, you want to publish them on different domains, so the language switcher doesn't work, correct?

No, they are currently under the https://apisix.apache.org/ domain, with English blog https://apisix.apache.org/blog/ and Chinese blog https://apisix.apache.org/zh/blog/.

The problem I encountered is the i18n feature requires 1-to-1 binding of blogs in each language. For example, I have a blog in English called A, then there must be a blog in Chinese called A' to serve the i18n purpose.

As our team grows and diverges, our demand for the i18n feature also changes. We want some blogs published in one language only, and still under the same domain. Then I tried Case1 and Case2, and the i18n feature could not meet our demand.

[Josh-Cena]

Oh, I see. I remember we have an issue somewhere related to that, but I can't find one. We also get lots of questions about that, most recently #7040.

We do expect the site's route structure to be isomorphic across locales: if /blog/foo exists, /zh/blog/foo must also exist, and vice versa. I don't know if breaking that contract would be very sensible—what kind of UX do you expect when the translated counterpart doesn't exist?

[yzeng25]

what kind of UX do you expect when the translated counterpart doesn't exist?

For Case 1 with English blog only, I think clicking on the language switch button and redirect to the summary page of Chinese blog, or the other language's blog summary page in general. This basically says "we don't have a corresponding blog in the other language and here is the list of the blogs we have." I think this UX is better than a default 404 page.

For Case 2 with Chinese blog only, it is similar to case 1. But before getting into the scenes in Case 1, we need some kinds of work-arounds to make it show up in in local preview, online preview, and the production.

I read through #7040 , and think maybe the i18n can be default 1-to-1, but with some flexibilities on the users' end, let them decide whether 1-to-1 is always necessary as team grows and demand changes.

[Josh-Cena]

I've triaged a few i18n-related issues. You can look through domain: i18n Related to the i18n system since a lot of them look related to your use-case.

[slorber]

@yzeng25 I understand this use-case, but we don't currently support it.

We expect both blog posts to exist in both languages. We also expect those 2 pages to have the same slug:

This is something we could work on, but it's not easy, due to the historical way we sandbox each localized site as a totally different SPA. (ie 3 locales = 3 SPA built one after the other)

To be able to switch from one locale to another, now one localized site would have to know about the existence/non-existence of pages in other localized sites. The language switcher would be more complex, requiring more global data about all your localized sites, leading to a performance penalty.

Similarly, we would have to handle this in SEO metadata, so that we don't output broken links in those metadata:

---

I don't think it's worth or easy to solve these problems.

However a workaround could work fine for your use-case: if a blog post does not exist in a given language, you can still create a MDX file for that language, but instead of displaying markdown content, you can just add a client-side Redirect:

---
id: my-chinese-only-blog-post
description: will redirect to blog home
---

import {Redirect} from '@docusaurus/router';

<Redirect to="/blog" />;

https://docusaurus.io/docs/docusaurus-core#redirect

It's not the best to do client-side redirects but still better than nothing.
And you can also add a server-side redirect in your host config.

[yzeng25]

OK got it. We did a similar workarounds as well. We modified the language switch button, when click on it, it jumps back to the blog summary page.

Thanks @slorber for your detail explanation, really appreciate it!