Make incomplete translation UX coherent, and the DX flexible #9947
Replies: 1 comment
-
Hey 👋
We don't support that because Docusaurus assumes you can switch from one page to another by simply using the locale dropdown, assuming that when there is If you want to display different content on a per-locale basis, you can still build one different Docusaurus site per locale instead, and would get that result. And it would become your responsibility to implement a locale dropdown that matches the UX you want to achieve here, which will be opinionated. With this kind of setup, you can still share most of your infrastructure across locales, and can use env variables in the config file to load different data. For example the docs plugin could use
By "article" do you mean a doc? or a blog post? 🤷♂️ Those things have different layouts, behaviors and it's not that simple. For docs still appear in autogenerated index, and blog posts in paginated views, and it feels like a really bad UX to click on a link and be constantly presented a 404 😅 I'd much rather see content in English.
We don't have that feature, but fortunately, you can build it yourself thanks to Docusaurus flexible primitives, notably swizzle and the v3.1 parseFrontMatter hook {
markdown: {
parseFrontMatter: async (params) => {
const result = await params.defaultParseFrontMatter(params);
const isDefaultLocale = process.env.DOCUSAURUS_LOCALE === 'en';
const isFromI18nFolder = params.filePath.includes('/i18n/');
result.frontMatter.isNotTranslated = !isDefaultLocale && !isFromI18nFolder;
return result;
},
},
} import React from 'react';
import Content from '@theme-original/DocItem/Content';
import Admonition from '@theme/Admonition';
import { useDoc } from '@docusaurus/theme-common/internal';
export default function ContentWrapper(props) {
const { frontMatter } = useDoc();
return (
<>
{frontMatter.isNotTranslated && (
<Admonition type="warning" title="Not translated :/">
Malheuresement cette page n'est pas traduite :s
</Admonition>
)}
<Content {...props} />
</>
);
} You can display a 404 message in place of the English content if you want to. Exposing if a page is coming from a translation source (i18n folder) is a convenient shortcut I could consider adding.
I don't know what you mean here. Docs are organized by sidebar and meant to be read sequentially. We can't mess up with the original order that was defined by |
Beta Was this translation helpful? Give feedback.
-
My colleagues and I are almost to the point of go-live on a large website that we have migrated from Zendesk Guide. It has sixteen or seventeen locales, and is currently getting 2+ million visits per month.
Here's the thing: we haven't translated all the 300+ docs pages that exist in English.
What this means is that currently, as a user, if I go to an
index.mdx
page with an autogenerated set of cards listing the articles in that section, they're just a jumbled mix of English and non-English article titles.As a person who doesn't speak or read English, this would be terrible UX. Rather than empowering readers who do not read English, we're creating a tremendous cognitive burden on them. This seems contrary to the goal of i18n.
From what I understand, this is not... Modifiable, currently, in Docusaurus; 'the assumption is that all the docs content has been translated'; if this is incorrect, please set me straight. This is what my colleague @i18nlaurel was told on the Docusaurus Discord.
(...to do that up front would cost us $350k, at least)
Ideas for solutions
Allow displaying only translated content
Hey, it could be an option; only generate routes in each locale for docs that are present in that locale, at
./i18n/<locale>docusaurus-plugin-content-docs/current/
If an article has not been translated, give a 404
This was what we actually wanted; for the non-translated docs not to appear, and if a reader landed on a link to one, they'd get a 404 page which we would customize and point them towards submitting a translation on GitHub.
Alternatively, slap a CTA banner or call-out at the top of untranslated docs
If we can't fail gracefully to a 404, and have to have
default locale
content alongside translated content, it would be helpful if, upon page load, we could have an element which could be localized to the user's chosen locale at the top of the article, indicating the article hasn't been translated, and pointing them to the translation submission flow, it raise an issue, etc.This would be possible, in theory, now--but it would require persisting user locale in local storage, if I understand correctly, which has been discussed in a few places, but does not have a built-in option (or does it?)
At the very least, sort docs within sections (and within categories in autogenerated indices) by translation status
This would create the UX of "translated content up top, English content below," which at least would make a clear visual and logical distinction to the reader.
Making a fix
I would be happy to collaborate with the team and try to figure out a solution; I would love the assistance of the experts 🫡 in helping us to get this live.
Docusaurus is a huuuuge improvement in quality of life and DX for us, despite this and one other significant roadbump we hit with i18n, which I'll raise in a separate issue.
Beta Was this translation helpful? Give feedback.
All reactions