[i18n] The idea of translating slugs

[mariuszkrzaczkowski]

Have you read the Contributing Guidelines on issues?

• [X] I have read the Contributing Guidelines on issues.

Motivation

Referring to #3317 discussion and https://docusaurus.io/docs/i18n/introduction#i18n-non-goals

I wanted to present my idea for translating slugs.

Example configuration

i18n: {
 defaultLocale: 'en',
 locales: ['en', 'pl'],
 slugsMode: 'map', // <---  values: `path` or `map`
},

• path as it is now
• map based on the slugs map

Example md file

---
id: hello
slug: /test/bonjour
slugMap: /test/hello
---
...

There is a slugMap (parameter name proposal) parameter in the MD file from which the mapping will be created in the i18n//slugs.json file (js or json file). Alternatively, make one mapping file.

Example of a mapping file (i18n/<locale>/slugs.json)

{
 "/test/hello": "/test/bonjour",
 "/test/i18n": "https://docusaurus.io/docs/i18n/introduction"
}

The mapping would allow internal redirection and external redirection (a different address such as Crowdin) No slug in the mapping of switching to a particular language not possible.

https://docusaurus.io/docs/i18n/introduction#i18n-non-goals

Translation of slugs: technically complicated, little SEO value

I'm not a node/react programmer but it doesn't seem to have a hard time

https://github.com/facebook/docusaurus/issues/3317

Slugs Should we allow to create custom slugs per language? If we do that, to be able to switch from one lang to the other without loosing context (the doc you are currently reading), one version would have to be aware of the slugs of all the other language versions, which might be quite a lot of data.

With current Internet connections and available equipment, this does not seem to be a problem.

How do we access such data in a performant way?

Handling custom Slugs can be efficient , the mapping only needs to be loaded into memory once. Or you can divide the mapping into smaller files, e.g. one level of URL path one file .

path : docs/i18n , mapping file i18n/<locale>/docs/slugs.json or i18n/docs/slugs.json path : docs/i18n/introduction , mapping file i18n/<locale>/docs/introduction/slugs.json or i18n/docs/introduction/slugs.json

Self-service

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

[slorber]

The idea of creating a mapping is of course a possible solution, and an idea I already had. But only the execution matters 😅 .

I'm not a node/react programmer but it doesn't seem to have a hard time

This remains unexecuted due to lack of time and not being a top priority, not because we didn't think about it.

I'm definitively open to a solution if anyone is willing to create a POC considering those constraints:

• it must scale well for very large sites without leading to loading eagerly a mandatory large JSON mapping file
• the slug translations workflow must be clear, for both Git and Crowdin based translated sites
• this should work for all 3 content plugins, but also enable third-party plugin authors to allow slug translations as well?

---

IMHO we don't want to have a slugMap and maintain such mapping manually, and the technical solution should handle everything automatically without having users to even think about it. The mapping file should rather be automatically generated into the build folder instead of being in i18n/<locale>/slugs.json. This probably requires a new lifecycle hook so that plugins can report a mapping is required when the localized path is different from the original path (and we may need to read 2 md files instead of 1)