Docusaurus: Broken links in example `index.js` because of language

[JoelMarcey]

Is this a bug report?

Yes. In the example index.js we have a line let language = this.props.language.... However, in generate.js and particularly metadata.js we are actually setting the permalink on the assumption that the language isn't set.

if (languages.length === 1 && !siteConfig.useEnglishUrl) {
    metadata.permalink = 'docs/' + metadata.id + '.html';
  } else {
    metadata.permalink = 'docs/' + language + '/' + metadata.id + '.html';
  }

But in the code before this, we are actually setting this.props.language to en by default, I think. So we are conflicting.

There are a few ways I can fix this, but I need to come up with the best way.

Have you read the [Contributing Guidelines]

Yes, of course. I helped right them :)

Environment

N/A

Steps to Reproduce

1. yarn global add docusaurus-init
2. docusaurus-init
3. mv docs-examples-from-docusaurus docs && mv website/blog-examples-from-docusaurus website/blog
4. cd website
5. yarn run start
6. Go to http://localhost:3000
7. Click on the Example Link Button
8. See 404.

Expected Behavior

The button links should go to an actual docs page.

Actual Behavior

The button links go to a 404-ish page.

Reproducible Demo

Run the steps above.

[neilsutcliffe]

I can have a look tomorrow at this as I've been messing around with the language stuff recently. For now sleep.

[neilsutcliffe]

There are a few ways I can fix this, but I need to come up with the best way.

The example website from docusaurus-init does not have a languages.js

I am a bit concerned though the default language is English. I'm trying to hack together something where any documents in the root docs/ folder do not get a language tag in the metadata.

// I don't have a language set!
"doc4": {
    "id": "doc4",
    "title": "Other Document",
    "source": "exampledoc4.md",
    "permalink": "docs/doc4.html",
    "localized_id": "doc4",
    "sidebar": "docs-other",
    "category": "First Category",
    "next_id": "doc5",
    "next": "doc5",
    "next_title": "Fifth Document"
  },

If we don't have a language.js file, then we don't need any prefixes for language and it is a simple markdown file server. This might appear to be the case, but all the root docs have an 'en-' prefix in their metadata.

If a language is requested then we should try to find the correct one, and if this fails we should fall back to the version without the language prefix.

I've got a fix on the way, but it is very ambitious and likely to break stuff, and will need extensive testing, especially with the GitHub pages stuff.

[JoelMarcey]

I am very interested in looking at your fix.

I was thinking one approach that we would make en the default if not languages.js is not provided, sort of like we do now and that all links will have a language component to it. e.g., xxx/docs/en/doc.html

Yours is generally the opposite thinking of that, which may be ok too.

[JoelMarcey]

If there is no agreement to a fix in relatively short order, I may just add useEnglishUrl: true to the examples/core/siteConfig.js file so that we can at least make the links work short-term.

[neilsutcliffe]

I would be tempted to remove the language part from the links instead, after all it's impossible for multiple languages to work with the default docusaurus-init file.

In order to get links other than /en/ to work would require adding stuff (languages.js, translations and crowdin) to the demo site.

At least when I'm testing http://localhost:3000/test-site/docs/doc1.html worked fine.

Having /en would also make it behave differently than the links in the header.

[JoelMarcey]

I think that's fair.

Although, I will say, 9 out of the 10 Docusaurus users showcased in https://docusaurus.io/en/users.html use the xxx/docs/en/doc.html format, even though not all have translations. They may have copied a language.js file from the Docusaurus site or something.

The only site that doesn't use that format is React Native -- a major site, of course :)

[richardzcode]

Made a PR for it. Not a small change. More reviews are better. :)

[richardzcode]

The PR failed on CircleCI. Not sure what's going on. I've run tests and check prettier locally seems no issue.

[JoelMarcey]

@richardzcode Excellent! Thank you so much. I am reviewing it now.

Re: CircleCI - today, I turned on Circle for PRs so we can see tests failing before they land :) Looking at the details, it seems like it is a Prettier issue; so I am going to import your PR locally and check it out.

[JoelMarcey]

I am also interested in seeing how @richardzcode's approach is similar or different to what @neilsutcliffe was thinking as well.

[JoelMarcey]

@richardzcode I commented on the PR re: the prettier failures.

[richardzcode]

It was a stupid error. I ran prettier but didn't commit prettier changes...

Yes, I think @neilsutcliffe and I are on the same direction. We all agree if no language.js, there shouldn't be language prefix. This approach is a more fundamental change rather than a quick fix. Need to be careful here.

[neilsutcliffe]

We are on the same page. Exactly the same page.

https://github.com/neilsutcliffe/Docusaurus/tree/fix-translation-urls for reference. Don't PR it, it is is broke.

Not the best way to wake up in the morning admittedly.

[neilsutcliffe]

So feel free to cherry pick from my working copy. It's not in a PR ready state like this is.

I also added a lot of comments to server.js as I found it hard to follow, especially the file system lookup area for pages.

I do like the way you have moved away from lacking a translation.js check in every file.

If I can elaborate further though. I think that even if languages are enabled, there should be a generic undefined file which is used as the basis for crowd translation. It could hypothetically be the case that the generic files are say in Chinese, and that the English files have to be translated from it.

And that any request which cannot find a localised version will fallback to that.

As for the il8n files. I'd propose a default.json file as an undefined.json file is pretty hard to look up in an array.

[JoelMarcey]

Reopening this because some links I found in docusaurus.io that were broken. So I reverted #316 for now. Investigating.

[tioback]

In case you're not using languages, this isn't exactly a fix, but a workaround, so create a languages.js file on the project's website folder with the following content:

module.exports = []