[i18n] Making everything translatable (website title, description...)

[MisterFISHUP]

🚀 Feature

First of all, the i18n feature of Docusaurus is terrific, thanks a lot!

It seems that the website's title can't be translated. It's not a big problem if the website title is just a simple name or doesn't have much meaning. However, It's really not ideal especially when the website uses languages that use different alphabet: imagine the main language of the website is Chinese (or Hebrew, Thai, Russian, etc) and the website title is also written in this language, then all final html pages' title will contain this website title, even for pages written in secondary/other languages (English for example), which is a bit bad for viewers and SEO since the website title in the html title is almost unreadable.

Thus, I think it's a good idea to include the possibility to translate the website title in the i18n feature, to improve readability and SEO in the cases illustrated above.

Have you read the Contributing Guidelines on issues?

Yes.

Motivation

See above.

Pitch

It would be great if the website title can be translated just like how the navbar/footer/react code is translated: add translations in some json file in i18n directory. Or even better: provide the website title translation in i18n in docusaurus.config.js directly (maybe in localConfigs for example, with a optional field for website title translation).

PS. Still need to mention this again: thanks for the awesome i18n feature!

TODOs

• site metadata in docusaurus.config.js
  • Website title
  • Announcement bar
  • Logo alt
  • Tagilne
  • Copyright
• Admonition title
  • Blocked by 3p deps
• Strings in plugin options
  • Blog sidebar title
• DocSearch model
  • Blocked by 3p deps

[slorber]

Thanks for the feedback :)

This has been reported here too: #4480

I was thinking of adding i18n/en/site.json or something, allowing you to provide title and tagline for example.

I think it's a better place to translate content, particularly when you have a long list of locales: not sure we want to maintain a lot of translations in the config.

But at the same time, I'd also like a locale to be able to "override" config setting somehow, just not sure what this API should look like and need to think more about this.

[MisterFISHUP]

@slorber Agree with you, and yes it is not evident how to design this API...
Besides the title, it would also be nice to be able to choose different img (social share image preview) for different locales, since this image often contains the site title (and other words/sentences depending on the current locale).
I also noticed the html in footer is not translatable. I can imagine some cases where the html contains texts depending on locales (ex: alt tag, title tag or just normal texts inside an element), so I think making it translatable would also be a good idea.

To sum up, here is a small list of untranslatable things I noticed:

• title (website title): because the html document title uses it (ex: html document title = <description> | <title>)
• img (social share preview): may contain texts that need to be translated
• announcement bar: simply because it contains texts depending on locales
• html string in footer item: may contain texts that need to be translated

Making the above things translatable can avoid unreadable texts for visitors and provide better SEO (better html document title)

Other untranslatable things:

• tagline: it's not used anywhere by default so strictly speaking it's not really an issue
• logo alt in navbar: it's also an untranslatable string, but it's less important to be honest

[slorber]

Thanks @MisterFISHUP for the exhaustive reporting.

• site title/description/tagLine: generating a site.json is probably better. It will also simplify translating those data through Crowdin for users that use it (or another SaaS)
• image/favicon: I'll add a i18n/<locale>/static folder to override the default static assets
• announcement bar/html footer items/logo alt in navbar: those are just missing theme translations Note html items would have to be translated in html, not very convenient

Does it make sense?

[MisterFISHUP]

@slorber That sounds great! Moreover, the two solutions site.json and i18n/<locale>/static look very logic/natural.

A few comments:

• Maybe I'm wrong, I don't think there is description in the current site config. For example, if description is not provided in a page (react or md), then the generated html won't have any description.

• For the i18n/<locale>/static folder, if I understood correctly, it's not restricted to image/favicon: once it's implemented, we can override any static assets, am I right?

• I agree that html items will have to be translated in html, but I think when we use the translation API (at least the current one), the generated json file will have the original string in that field, which is handy for translation imo since we can just translate the locale-depending part.

  Making html footer items translatable would be useful if we want to turn a plain-text footer item into a more interesting one, e.g. add an image beside the text or style the text with some css class. With the translation API, I think when we open the json file, since the original html string is there, we can just change the 'text' part and don't need to touch any other html markup.

By the way I noticed the copyright in the footer is often of form `Copyright © ${new Date().getFullYear()} My Project, Inc. Built with Docusaurus.`, just to avoid hardcoding the current year, but it seems that we need to hardcode this in the translated copyright (this has nothing to do with copyright of course, it's just a common use case). I'm actually ok with this but maybe this could be improved? Sorry that this is not fully related to the issue here, but I'm not sure if it's really an issue to open an issue neither.

[slorber]

Another case is the admonitions when they don't have a title:

:::caution

We only copy `.md` and `.mdx` files, as pages React components are translated through JSON translation files already.

:::

It requires to use :::caution Attention to ensure the admonition title is translated:

We should find a way to provide automatic default admonition titles in the selected language

Reported here: #3526 (comment)

Remark-admonition issue: elviswolcott/remark-admonitions#35

[slorber]

The blog sidebar title is not translatable (reported in #3643 (comment))

See: https://docusaurus.io/fr/blog

This label is provided by config for now:

[slorber]

The DocSearch modal is also not translated currently.

We'll have to wait for Algolia to provide APIs to translate it.

[slorber]

Versioned sites have a "Versions" label on the mobile sidebar that we currently cannot translate:

[slorber]

The blog blogSidebarTitle option is not translatable (#5350)

[Josh-Cena]

The blog blogSidebarTitle option is not translatable

Didn't experiment, but could it be translatable by wrapping it with <Translate> here?

docusaurus/packages/docusaurus-theme-classic/src/theme/BlogSidebar/index.tsx

Line 28 in 416e2a7

{sidebar.title}

The translations will still be written in code.json

[slorber]

The <Translate> component is only meant to be used for hardcoded labels in React components, and code.json becomes available in the JS runtime in the React context. It is not really suited for the Node.js side, user-provided config, or for dynamically created translation keys.

For all other use-cases (including blogSidebarTitle), we have plugin translation lifecycles so that a plugin can translate the content before passing it to the React components.

Examples:

• https://github.com/facebook/docusaurus/blob/master/packages/docusaurus-theme-classic/src/translations.ts

• https://github.com/facebook/docusaurus/blob/master/packages/docusaurus-plugin-content-docs/src/translations.ts

• getTranslationFiles permits to know which files the plugin should write to disc when using docusaurus write

• translateThemeConfig / translateLoadedContent is responsible for "applying" localized translation files to the plugin content/theme config

[Josh-Cena]

I'll look into some of them, and it would be great if we can make a task list for this issue

[Josh-Cena]

For the theme config, I think there're a lot that can be translated besides the announcement bar: metadata, light/dark icons, etc. Maybe put them in a docusaurus-theme-classic/config.json file?

[slorber]

Yes something like themeConfig.json can make sense if it's useless to split a single label in a separate file.

---

ATM blog tag labels are not translatable, and docs tag labels (#3646) won't either. I don't think it's a very high priority for now (nobody noticed) so we'll figure this one last.

[Josh-Cena]

ATM blog tag labels are not translatable

Not sure what you mean, since at least tags in Markdown front matter are translated once you provide different front matter in the translated MD file?

[slorber]

Oh you are right didn't think about that 😅

[slorber]

It's not possible to customize sidebar items' labels of type doc/ref (only labels provided in the sidebars.json, as the frontmatter such as sidebar_label can be translated with md already).

See comment here: #5593 (comment)

[azeeka]

It's not possible to customize sidebar items' labels of type doc/ref (only labels provided in the sidebars.json, as the frontmatter such as sidebar_label can be translated with md already).

See comment here: #5593 (comment)

Has that issue been closed? So it is not going to be implemented?

[Josh-Cena]

Has that issue been closed? So it is not going to be implemented?

That PR isn't really going in the right direction, and TBH I don't think I even understood the use-case. We are recently doing lots of changes with the sidebar (#5830, #5782), and we will see how translation works after that

[cainmagi]

Dear developers of Docusaurus:

The i18n for the index pages automatically generated by generated-index is not working, although I can find the i18n config files and have written the translation, see the example below:

• Codes where the original text of the index description is defined 📝
• Codes where the translation is written 📝
• The page built by Github Action can be viewed here 🔗, where the translation does not work correctly, and the text is still in English.

By the way, I suggest your teams to check your own website. Take a look at this example 🔗, please. I am not sure whether you have written the translation. But the page description is definitely not translated yet.

So I suspect that there should be a bug currently. I hope your team can fix this issue soon.

Thank you!

[Josh-Cena]

@cainmagi Thanks for the report. Will be fixed in #7233

[cainmagi]

@Josh-Cena Thank you! I will wait for the next release.

[slorber]

Admonition default titles are now translatable (#7556) (canary or next release)

Please help us and provide the missing admonition translations for your language: https://github.com/facebook/docusaurus/tree/main/packages/docusaurus-theme-translations/locales

(tip: also provide all the other missing translations at the same time)

[slorber]

Note for myself:

Autogenerated category labels (_category_.json) can be translated through JSON files already.
However it is not always convenient or intuitive, and we should probably make it easier to translate using a _category_.json file in the localized folder directly (reported in #8213). But being able to translate those labels with both _category_.json files and JSON i18n files might also be confusing, as one of them has to be used in priority.

[slorber]

We don't have a good API design to translate many things of the site config at the moment.

However I'd like to present you a temporary workaround introduced in #8677.

Your site config will receive a process.env.DOCUSAURUS_CURRENT_LOCALE environment variable that you can read from the config file.

IMPORTANT: the docusaurus build will first load the Docusaurus config with an empty value for DOCUSAURUS_CURRENT_LOCALE. This is because... the i18n config is in the config file so we must first load it before being able to inject any value as an env variable. For this reason this env variable is only a best-effort awkward temporary workaround to unlock users. It is undocumented on purpose, not part of the public API, and will likely be refactored some day.

If you decide to use this variable, you'd rather program defensively and assume the locale value might be absent, and fallback yourself to your defaultLocale.

2 possible defensive examples, assuming "en" is your default locale:

process.env.DOCUSAURUS_CURRENT_LOCALE ??= "en"

function getSiteTagline() {
  switch(process.env.DOCUSAURUS_CURRENT_LOCALE) {
    case "fr": return "Mon site en Français";
    default: return "My English website";
  }
}

Some cases where DOCUSAURUS_CURRENT_LOCALE will be undefined:

• When Docusaurus first loads the config file on docusaurus build to get the i18n config
• When you run docusaurus start with no locale arg
• When you run any other docusaurus CLI script unrelated to i18n, that requires reading the config (swizzle, docs:version...)

The DOCUSAURUS_CURRENT_LOCALE env variable will be provided when:

• You run docusaurus build, only after the first load, once we start iterating over locales
• You run docusaurus build --locale fr
• You run docusaurus start --locale fr

Note: DOCUSAURUS_CURRENT_LOCALE is not designed to be set "from the outside". Please don't set this value as an env variable in your CI or local computer, it will be ignored.

I hope this makes sense and is not too confusing. Hopefully, we will provide a better way to translate the config later, but this should be good enough to unlock many use cases.

[chenyuncai]

Thanks @MisterFISHUP for the exhaustive reporting.

• site title/description/tagLine: generating a site.json is probably better. It will also simplify translating those data through Crowdin for users that use it (or another SaaS)
• image/favicon: I'll add a i18n/<locale>/static folder to override the default static assets
• announcement bar/html footer items/logo alt in navbar: those are just missing theme translations Note html items would have to be translated in html, not very convenient

Does it make sense?

Really need it. we sent our docs to a translate platform and push back to i18n dir. now we had to manually update the the image link to another image path and save new img files to a different dir.

[peirstom]

Just for tracking purposes:
Logo Alt is fixed
#8616

[volkantash]

"Recent Post" yazısı niye çevrilmiyor?
...
Why is not translating "Recent Post" text?

[slorber]

@volkantash you can translate this label thanks to the options.blogSidebarTitle and the workaround suggested here: #4542 (comment)

It's not super convenient, I agree, and we'll try to improve, but at least it is possible.

[kkhr1341]

ATM blog tag labels are not translatable

Not sure what you mean, since at least tags in Markdown front matter are translated once you provide different front matter in the translated MD file?

I think that @slorber had a point. We have a English site with Japanese and Chinese translation. So in the English version of a blog article we might set a tag like "Product" in the front matter, which would then be "商品" in the Japanese .mdx file.

On first view everything looks fine, as we get both a page for the "product" tag as well as for the "商品" tag.

1. .../blog/tags/product/
2. .../ja/blog/tags/商品/

However, we also get two 404 errors, as apparently no direct connection is formed between the English tag and the Japanese tag:
404 Error 1: .../blog/tags/商品/
404 Error 2: .../ja/blog/tags/product/

Maybe we made a mistake during our setup, but we think that the handling of tags and their translatability should be looked at one more time.

[slorber]

@kkhr1341 the translation of urls/slugs is not a goal of Docusaurus currently (see https://docusaurus.io/docs/i18n/introduction#i18n-non-goals). It would be quite complicated for us to support it properly, not just for tags but for all other urls as well.

However, the problem here is that your tag label is tightly coupled to the tag url segment.
If you keep using the same url segment for all the localized sites, you shouldn't get 404 errors anymore, and indeed we should let you translate the tag label.

This is already possible, with an historical API that is lightly documented but I don't like it much because it's awkward and you'll have to add the permalink to all your docs using this tag, ensuring they remain in sync:
https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-blog#tags

tags: 
  - label: "商品"
    permalink: "product"

In the future, we'll likely have a tags.yml registry, similar to how we handle authors.yml

[alienzhangyw]

How to translate navbar and footer with variables?

For example, I load brandName from ENV file when building with CI:

but the footer.json and the navbar.json generated by write-translations is hard coded. How can I change title or copyright texts during build, while keeping other messages translated?

[slorber]

@alienzhangyw you can use process.env.DOCUSAURUS_CURRENT_LOCALE in the config file, as explained here:

#4542 (comment)

If you prefer to translate things thanks to env vars, you can also delete the generated files here:

i18n/en/docusaurus-theme-classic/navbar.json
i18n/en/docusaurus-theme-classic/footer.json

You can also remove individual keys from this file, if you only want your config to take over for certain keys. Docusaurus will use this file's labels in priority if it exists, but it can also be "partially complete" and we'll merge labels from your config/env with what's in those files.