Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

404 page breaks translations #2022

Open
mgeisler opened this issue Apr 22, 2024 · 2 comments
Open

404 page breaks translations #2022

mgeisler opened this issue Apr 22, 2024 · 2 comments
Labels
bug Something isn't working good first issue Good for newcomers

Comments

@mgeisler
Copy link
Collaborator

When you call mdbook build, you automatically get a 404.html page in the root of the output directory.

Since we run mdbook build for each translation, we end up with a structure like

/404.html
/da/404.html
/de/404.html
...

The root 404.html page is automatically used by GitHub Pages when a page cannot be found. Note that the URL doesn't change: the content of 404.html is simply returned to the browser.

Now, this doesn't work well with our translations: you end up with the English 404.html regardless of which translation you're currently viewing. We should fix this so that people get the correct version. The output.html.input-404 setting is for that.

Simply setting this is not enough: GitHub Pages doesn't know anything about the translation sub-directories, so it will continue to show people the root 404.html page. I think we can fix this by injecting a bit of JavaScript into the 404.md file which mdbook build uses to generate the 404.html page.
@mgeisler mgeisler added bug Something isn't working good first issue Good for newcomers labels Apr 22, 2024
@mgeisler mgeisler transferred this issue from google/mdbook-i18n-helpers Apr 22, 2024
@aishwaryavenkatesan
Copy link

Hi @mgeisler , can I work on this issue? I'm pretty new to open source contribution.

@mgeisler
Copy link
Collaborator Author

Hi @aishwaryavenkatesan, you sure can! It would be wonderful to have someone look at this and help us come up with a good solution.

Is the problem described okay in the issue? In short, the problem is that you always get the English 404 page. If you go to https://google.github.io/comprehensive-rust/hello-world.html, you see the side bar is in English. Compare to https://google.github.io/comprehensive-rust/es/hello-world.html, where the page and the sidebar is in Spanish.

The problem is that https://google.github.io/comprehensive-rust/es/does-not-exist.html brings you out of the Spanish translation and back into the English original.

I guess you're new to GitHub Pages, so I suggest you create a new empty repository on GitHub and play with them. Follow the Create a GitHub Pages site tutorial to get started. Use the main branch as your "publishing source" and create a very simple index.html page containing just

<!doctype html>
<html lang="en-US">
  <head>
    <title>My test page</title>
  </head>
  <body>
    <h1>Hello!</h1>
  </body>
</html>

  • When you've committed that to your main branch and configured GitHub Pages publishing, then you should be able to load the page in your browser.

  • Now go to a page that doesn't exist on your little site — you'll get a 404 error from GitHub. Add a 404.html page as well to replace the default error page with a custom page.

  • Now you can start replicating the problem above: go to xx/does-not-exist.html to simulate following a broken link in the xx translation. Notice that you are served the 404.html page the root directory, even though you asked for a page in a subdirectory. So even if you create a xx/404.html page with a nice translated 404 page, this file will never be used by GitHub.

I believe we should be able to detect the current URL (xx/does-not-exist.html) with some JavaScript in the 404.html page. The JavaScript can see that we should actually use the xx translation.

At this point, the JavaScript could perhaps load the correct xx/404.html page in an iframe or similar... something that would replace the English text with a translated. It is also important that the search works correct by searching the translation, not the English book.

I'm not 100% sure about the last steps, but let us start by replicating the problem 😄

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
bug Something isn't working good first issue Good for newcomers
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@mgeisler @aishwaryavenkatesan