facebook / facebook/docusaurus

[i18n] The idea of translating slugs

Open
#8,521 1 comment 0 reactions 0 assignees View on GitHub
proposal
Dominant language
TypeScript
Stars
66.2k
Forks
10k
Avg merge
1d 3h
Merged PRs (30d)
52

Description

### Have you read the Contributing Guidelines on issues?

- [X] I have read the [Contributing Guidelines on issues](https://github.com/facebook/docusaurus/blob/main/CONTRIBUTING.md#reporting-new-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
```js
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
```md
---
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//slugs.json`)

```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//docs/slugs.json` or `i18n/docs/slugs.json`
path : `docs/i18n/introduction` , mapping file `i18n//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.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.