Audit i18n SEO issues: hreflang, x-default, canonical...

[slorber]

Have you read the Contributing Guidelines on issues?

• [X] I have read the Contributing Guidelines on issues.

Motivation

It has been reported that we may not implement correctly meta page headers for SEO

https://github.com/facebook/docusaurus/issues/3317#issuecomment-975150571 https://github.com/facebook/docusaurus/issues/3317#issuecomment-989136495

Let's discuss here what we do wrong exactly, and what we should do instead.

Please link to reference material from an SEO authoritative source (Google, Moz...) whenever possible. It's not always so easy to interpret these docs correctly.

Please give concrete examples of what we do wrong and how to solve the problem.

• Page link: ...
• Current wrong meta headers: ...
• Expected (good) meta headers: ...
• Ref link: ...

cc @mxhdx @thadguidry

Self-service

• [ ] I'd be willing to do some initial work on this proposal myself.

[Josh-Cena]

Also #6011

[Josh-Cena]

Another possibility we can consider: a url field for each locale. This would set the URL context for each locale (while omitting it would result in a different base URL), in case it's deployed to a different URL than https://example.com/<locale>/.

[slorber]

Totally agree on this @Josh-Cena , something I want to add for a while already as currently, deployments using multiple domains have some wrong SEO tags and it's complicated to use the i18n locale dropdown.

Also related to https://github.com/facebook/docusaurus/issues/4723

I was thinking if we needed a feature to customize a site config on a per-locale basis, but couldn't figure out a good API for this, and it may be overkill. Just allowing to override some specific attributes like URL, baseUrl, etc may be good enough.

[Josh-Cena]

@slorber If we now support config creator functions, could we just pass in locale as a parameter and allow users to return different configurations? This means we solve:

• SEO;
• Multi-domain deployment;
• Translation of text hardcoded in the config...

[slorber]

Thought about it, but not 100% sure it's a very good API 😅 it would work but it's a bit weird at the same time, considering the config must be read first before we can know which languages to build

[Josh-Cena]

I guess it would be fine, because the language could be passed down from CLI arguments. In loadContext, the locale might be part of the context. We can require users to return a full array of i18n configs if locale is undefined because that would be the default case (before we know the existence of any locales).

[slorber]

I guess it would be fine, because the language could be passed down from CLI arguments.

In case the user runs docusaurus build we don't get an explicit locale from the user.

The best we could do is provide en as a fallback, but then it would be particularly awkward if user returns an i18n config with a different default locale 🤷‍♂️

IE imagine I build a french blog, I get en (or undefined) and return i18n.defaultLocale = 'fr' => this would work but it's weird 😅

To make this less awkward we'd need to load locales + defaultLocale independently from the site config

[Josh-Cena]

@slorber There's no og:locale meta. Is that an oversight?

[slorber]

@slorber There's no og:locale meta. Is that an oversight?

Yes, it seems we can add og:locale and og:locale:alternate 👍

[slorber]

Another possibility we can consider: a url field for each locale. This would set the URL context for each locale (while omitting it would result in a different base URL), in case it's deployed to a different URL than https://example.com/<locale>/.

Totally agree on this @Josh-Cena , something I want to add for a while already as currently, deployments using multiple domains have some wrong SEO tags and it's complicated to use the i18n locale dropdown.

Also related to #4723

I was thinking if we needed a feature to customize a site config on a per-locale basis, but couldn't figure out a good API for this, and it may be overkill. Just allowing to override some specific attributes like URL, baseUrl, etc may be good enough.

The hreflang tags can now be fixed as part of https://github.com/facebook/docusaurus/pull/11316 by providing a custom url per locale (fr.docusaurus.io for example)

---

@slorber If we now support config creator functions, could we just pass in locale as a parameter and allow users to return different configurations? This means we solve:

• SEO;
• Multi-domain deployment;
• Translation of text hardcoded in the config...

In https://github.com/facebook/docusaurus/pull/8677 we introduced a DOCUSAURUS_CURRENT_LOCALE env variable, more as a workaround than a real public API.

It is not really a good fit for a multi-domain deployments because for a single localized site, we should be aware of all the alternative URLs possible so that we output the correct hreflang tags, so a locale config feels more appropriate.

I would find this awkward if the English site were calling the config creator function for each locale just to retrieve all the alternate url/baseUrls. It is more natural if the English site only calls it once with env DOCUSAURUS_CURRENT_LOCALE=en.