Internationalisation: Fall back to specified language if translation is missing

[hamishwillee]

Is your feature request related to a problem? Please describe.

The more pages you have the longer it takes to build a site. Adding each translation can very significantly increase the number of pages. If there is a fallback for missing translations then you only have to build the pages that are actually translated.

This also is better for users, as they see what is translated and what is not more clearly.

Describe the solution you'd like

I'd like to be able to specify a default language. If a page in any other language is not found, I'd like the system to fall back to the version in the default language, and only if that is missing fall back to 404.

Note that I don't want to use root as the default language. This is a common approach, but it doesn't work well for shared assets unless they are in "public", because the root will have a different relative path to these compared to translations.

Describe alternatives you've considered

No response

Additional context

Docsify does this, and some other systems.

Validations

• Follow our Code of Conduct
• Read the docs.
• Read the Contributing Guidelines.
• Check that there isn't already an issue that asks for the same feature to avoid creating a duplicate.

[babakfp]

Just asking a question, is it possible right now to fall back to the default language (root)?

[hamishwillee]

Just asking a question, is it possible right now to fall back to the default language (root)?

Not for me. I mean, falling back to root has bigger problems because it means you can't have shared images unless they are in public and are reference by an absolute URL. Using root as recommended by many SSG means you are pretty much forced to have separate images for every translation.

[babakfp]

Can you check this out if it does what you are asking for?

#3312

but it doesn't work well for shared assets unless they are in "public", because the root will have a different relative path to these compared to translations.

I don't know about this. I don't know how to test it. Let me know if it works or not. Thanks.

[hamishwillee]

What you're proposing there is better than I asked for. In particular allowing each language to choose its own fallback means that you could have fallback to language variants - e.g. dialects. So this is excellent.

Note that I have not actually tested this patch. I tried - but I'm having trouble working out how get my own docs to build in the context of this repo (and modifying the existing docs to test this seems hard).

[hamishwillee]

but it doesn't work well for shared assets unless they are in "public", because the root will have a different relative path to these compared to translations.

I don't know about this. I don't know how to test it. Let me know if it works or not. Thanks

Sorry, I have not been clear. I am not saying that there is a bug of any kind here in vitepress.

What I am saying is that I don't like the concept of using "root" as a fallback. I'll explain below but feel free to ignore - your PR looks great.

The "root" approach works fine if your images are in the same directory as your docs, because you just access them relative to the current document ![my image](myimage.jpg).
However with a big project and you don't want to localise the images then you are more likely to have the images in a shared folder. IN this case you access them by relative URL - e.g. ![my image](../../assets/myimage.jpg). That path ends up at a different location in "root" than in any translation.
So you end up being forced to either have the images in "public" so you can use an absolute URL, or duplicating the images for every translation).

[babakfp]

What you're proposing there is better than I asked for. In particular allowing each language to choose its own fallback means that you could have fallback to language variants - e.g. dialects. So this is excellent.

Note that I have not actually tested this patch. I tried - but I'm having trouble working out how get my own docs to build in the context of this repo (and modifying the existing docs to test this seems hard).

Thanks.

You can close the repo, fetch the changes. Open the project in your workspace in vsCode. pnpm i. pnpm run docs. Open the URL logged in the terminal. That's it. Add your locales config, etc same as how you do it in your project.

[babakfp]

The "root" approach works fine if your images are in the same directory as your docs, because you just access them relative to the current document ![my image](myimage.jpg). However with a big project and you don't want to localise the images then you are more likely to have the images in a shared folder. IN this case you access them by relative URL - e.g. ![my image](../../assets/myimage.jpg). That path ends up at a different location in "root" than in any translation. So you end up being forced to either have the images in "public" so you can use an absolute URL, or duplicating the images for every translation).

If I understood you correctly, use this https://vitepress.dev/guide/asset-handling#base-url.
No matter from what path/URL you are accessing the assets inside public, if you use the base URL, you can load the assets by the same path. Like /my-image.png.
🤔

[hamishwillee]

That works if you're keeping all your assets in public. But there must be a reason why the docs recommend that instead "you can, and should, reference any assets using relative URLs"