[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)