docs: add comprehensive i18n SEO guide #10868
+93
−0
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -218,3 +218,96 @@ Docusaurus uses your file names as links, but you can always change that using s | ||||||
| Search engines rely on the HTML markup such as `<h2>`, `<table>`, etc., to understand the structure of your webpage. When Docusaurus renders your pages, semantic markup, e.g. `<aside>`, `<nav>`, `<main>`, are used to divide the different sections of the page, helping the search engine to locate parts like sidebar, navbar, and the main page content. | ||||||
|
|
||||||
| Most [CommonMark](https://spec.commonmark.org/0.30/#atx-headings) syntaxes have their corresponding HTML tags. By using Markdown consistently in your project, you will make it easier for search engines to understand your page content. | ||||||
|
|
||||||
| ## Internationalization (i18n) SEO {#i18n-seo} | ||||||
|
|
||||||
| When your Docusaurus site supports multiple languages, it's crucial to implement proper SEO practices to help search engines understand and serve the right content to users. Here's how to optimize your multilingual site: | ||||||
|
|
||||||
| ### Language Tags {#language-tags} | ||||||
|
|
||||||
| Docusaurus automatically adds the appropriate `lang` attribute to your HTML: | ||||||
|
|
||||||
| ```html | ||||||
| <html lang="en"> | ||||||
| <!-- English content --> | ||||||
| </html> | ||||||
|
|
||||||
| <html lang="es"> | ||||||
| <!-- Spanish content --> | ||||||
| </html> | ||||||
| ``` | ||||||
|
|
||||||
| ### Hreflang Tags {#hreflang-tags} | ||||||
|
|
||||||
|
|
||||||
| Hreflang tags help search engines serve the correct language version to users. Docusaurus automatically generates these tags for all your language versions: | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| ```html | ||||||
| <!-- For your English pages --> | ||||||
|
There was a problem hiding this comment. There's no information in this code block that indicates that it's an "English page", so including this confuses readers. |
||||||
| <link rel="alternate" hreflang="en" href="https://example.com/en/doc" /> | ||||||
| <link rel="alternate" hreflang="es" href="https://example.com/es/doc" /> | ||||||
| <link rel="alternate" hreflang="x-default" href="https://example.com/doc" /> | ||||||
| ``` | ||||||
|
|
||||||
| :::tip Understanding hreflang | ||||||
|
|
||||||
| - Use `hreflang` to indicate language variants of a page | ||||||
| - Include all language versions, including the current page | ||||||
| - Add `x-default` for pages without targeting | ||||||
| - Always use full URLs in `href` attributes | ||||||
|
|
||||||
| ::: | ||||||
|
Comment on lines
+251
to
+258
There was a problem hiding this comment. Remove; this doesn't pertain to Docusaurus users. We already handle all of these by default. |
||||||
|
|
||||||
| ### Canonical URLs {#i18n-canonical} | ||||||
|
|
||||||
|
|
||||||
| For multilingual content, canonical URLs help prevent duplicate content issues: | ||||||
|
|
||||||
| ```html | ||||||
| <!-- In your English version --> | ||||||
| <link rel="canonical" href="https://example.com/en/doc" /> | ||||||
|
|
||||||
| <!-- In your Spanish version --> | ||||||
| <link rel="canonical" href="https://example.com/es/doc" /> | ||||||
| ``` | ||||||
|
|
||||||
| :::caution | ||||||
|
|
||||||
| Don't use canonical URLs across different language versions. Each language version should be treated as unique content. | ||||||
|
|
||||||
| ::: | ||||||
|
Comment on lines
+272
to
+276
There was a problem hiding this comment. Doesn't pertain to Docusaurus |
||||||
|
|
||||||
| ### Best Practices {#i18n-seo-best-practices} | ||||||
|
|
||||||
| 1. **URL Structure** | ||||||
| - Use clear language indicators in URLs (e.g., `/en/`, `/es/`) | ||||||
| - Keep URL structure consistent across languages | ||||||
| - Consider using country codes for region-specific content (e.g., `/en-us/`, `/es-mx/`) | ||||||
|
|
||||||
| 2. **Content Translation** | ||||||
| - Translate meta tags (title, description) for each language | ||||||
| - Maintain consistent heading structure across translations | ||||||
| - Adapt content for cultural differences when necessary | ||||||
|
|
||||||
| 3. **Default Language** | ||||||
| - Set a clear default language in your configuration | ||||||
| - Use `x-default` for language selection pages | ||||||
| - Consider your primary audience when choosing defaults | ||||||
|
|
||||||
| 4. **Technical Implementation** | ||||||
| ```js title="docusaurus.config.js" | ||||||
| export default { | ||||||
| i18n: { | ||||||
| defaultLocale: 'en', | ||||||
| locales: ['en', 'es', 'fr'], | ||||||
| localeConfigs: { | ||||||
| en: { | ||||||
| htmlLang: 'en', | ||||||
| path: 'en', | ||||||
| }, | ||||||
| es: { | ||||||
| htmlLang: 'es', | ||||||
| path: 'es', | ||||||
| }, | ||||||
| }, | ||||||
| }, | ||||||
| }; | ||||||
|
|
||||||
|
Comment on lines
+278
to
+313
There was a problem hiding this comment. This needs a rewrite. What's the purpose? I don't see any coherent structure here. Is it educating Docusaurus users how to implement better SEO for their own content using our framework (which is the goal), or is it advertising how Docusaurus handles everything under the hood (which is fine but unnecessary), or is it general education material about how to do SEO in a website (which wouldn't be topical for us)? I am assuming it's for the first purpose, in which case you just need to mention the following:
And then point to our Internationalization docs for anything specific about using i18n in Docusaurus. |
||||||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
No need for these H3 headings; there isn't enough information under it for it to be sectioned. Each section is just a single paragraph, which is enough as a signpost for sectioning.