fix(plugin-content-docs): enable docs translations

[SuperOleg39]

Motivation

Hello!

First, thanks for awesome work for made i18n so easy!

In our project, we use the same documentation file for few sidebars - every library doc live in API reference, and we try to group some docs by feature (routing, state management, etc.).

Sidebar for API reference doc and for feature may have different title, so we can't use frontmatter title for this, and i spend some time to find best way for differend sidebar translations per one document file.

Fortunately, @slorber already solve this problem, and left commented code in plugin-content-docs

If it don't break something, i want to enable docs translation functionality.
Fix translations.test.ts, because createSampleDoc don't create unique unversionedId, and translateLoadedContent create only translation for last doc.

Have you read the Contributing Guidelines on pull requests?

Yes

Test Plan

First, docusaurus write-translations --locale en should add new fields for every sidebar docs in i18n/en/docusaurus-plugin-content-docs/current.json

Second, docusaurus start --locale en should respect translations in current.json in sidebar and docs title

Related PRs

(If this PR adds or changes functionality, please take some time to update the docs at https://github.com/facebook/docusaurus, and link to your PR here.)

[facebook-github-bot]

Hi @SuperOleg39!

Thank you for your pull request and welcome to our community.

Action Required

In order to merge any pull request (code, docs, etc.), we require contributors to sign our Contributor License Agreement, and we don't seem to have one on file for you.

Process

In order for us to review and merge your suggested changes, please sign at https://code.facebook.com/cla. If you are contributing on behalf of someone else (eg your employer), the individual CLA may not be sufficient and your employer may need to sign the corporate CLA.

Once the CLA is signed, our tooling will perform checks and validations. Afterwards, the pull request will be tagged with CLA signed. The tagging process may take up to 1 hour after signing. Please give it that time before contacting us about it.

If you have received this in error or have any questions, please contact us at cla@fb.com. Thanks!

[netlify]

✔️ [V2]
Built without sensitive environment variables

🔨 Explore the source changes: b26bd4c

🔍 Inspect the deploy log: https://app.netlify.com/sites/docusaurus-2/deploys/61487633f15cf600088fe2e7

😎 Browse the preview: https://deploy-preview-5593--docusaurus-2.netlify.app

[github-actions]

⚡️ Lighthouse report for the changes in this PR:

Category	Score
🟢 Performance	96
🟢 Accessibility	98
🟢 Best practices	100
🟢 SEO	100
🟢 PWA	95

Lighthouse ran on https://deploy-preview-5593--docusaurus-2.netlify.app/

[facebook-github-bot]

Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Facebook open source project. Thanks!

[slorber]

Hi and thanks for the feedback.

I'm not sure to understand your use-case, can you detail and maybe share live URLs of your site with API ref and feature pages? And the source code if possible?

In my opinion, adding translation for frontmatter is not a good idea. It may be a good idea for your specific use-case, but may not be good for the rest of the users because they'll try to translate the frontmatter and those translations in md would be overridden by the translations of the i18n json files. Giving 2 ways to translate things makes the system more complex and less intuitive so we'll only add this if there's a really strong use-case that we can't solve in another way. That's why I must 100% understand your use-case :)

[slorber]

Note, I plan to introduce a docs plugin option callback createFrontMatter() that would allow you create/modify existing docs frontmatter. This can gives you the opportunity to introduce custom frontmatter like titleAPI and titleFeature, and map one or the other to the official title frontmatter according to your use-case and own rules. This may be a more generic solution to this problem.

[SuperOleg39]

Yes, i have a live example)

This document (untranslated for now) - https://tramvai.dev/en/docs/references/libs/router - available at two categories in sidebar: Feature.Routing and Reference.Libs

Document source is here - https://github.com/TinkoffCreditSystems/tramvai/blob/main/packages/libs/router/README.md

And for features, we want one title, for example - Our awesome router
For reference, another, just package name - @tinkoff/router

Shor version of our dynamically created and untranslated sidebars.json:

{
  "docs": {
    "Возможности": [
      {
        "type": "category",
        "label": "Routing",
        "items": [
          {
            "type": "doc",
            "label": "Библиотека @tinkoff/router",
            "id": "references/libs/router"
          }
        ]
      }
    ],
    "Справочник": [
      {
        "type": "category",
        "label": "Библиотеки",
        "items": [
          "references/libs/router"
        ]
      }
    ]
  }
}

Without thist PR, we can translate only categories in i18n/en/docusaurus-plugin-content-docs/current.json - sidebar.docs.category.Возможности and sidebar.docs.category.Справочник

And the question is how we can prodive two different title translations for one document?

[slorber]

I find it a weird pattern to use the same doc twice under the same sidebar with different titles, + the doc will be highlighted under 2 distinct categories, leading to a weird UX.

I don't think this use-case is good enough to support this new translation feature, unless you prove me it's a widely used and good practice documentation pattern to do so, by providing examples of live doc sites doing this or any ref material.

I'd suggest:

• Use an MDX partial for your doc: https://docusaurus.io/docs/markdown-features/react#importing-markdown
• Create one entry doc for each sidebar entry
• Use a different route/title/id/sidebar_label for each doc
• Import the shared MDX content in both entry files
• We have an issue with the TOC on MDX partials, but the trick we use on our changelog page might solve your problem: https://raw.githubusercontent.com/facebook/docusaurus/main/website/community/5-changelog.md

---

If you really want to use a single doc / route for this page, I'd recommend to use a ref:
https://docusaurus.io/docs/next/sidebar#sidebar-item-ref

I'd be fine to allow providing a custom label to a ref sidebar item, to support your use-case

---

In general we recommend to only use a doc once in a sidebar, so that we know this doc is bound to a sidebar.

Imagine 1 doc is used in 2 distinct sidebars: Docusaurus wouldn't know which sidebar to display when browsing that doc's URL, and it would pick randomly a (the first one afaik)

[slorber]

Going to close this because I believe there are better alternatives, but still open for discussion

[SuperOleg39]

Thank you for interesting advices, ref looks suitable for our case!

In a future, i think we don't really need to use the same doc twice, but it will be a complete rework, so i try to find compromises)

[slorber]

Thanks for understanding

Does it make sense to add a label in the ref item for your use-case? That would be way easier and I'm surprised we can't do this already

[SuperOleg39]

Just try to use ref, have a similar behaviour to

the doc will be highlighted under 2 distinct categories, leading to a weird

And label is working)

{
    "type": "ref",
    // see this label at sidebar
    "label": "TEST @tinkoff/router",
    "id": "references/libs/router"
}

So maybe label support already implemented?

[slorber]

I see. Indeed it looks like the code supports it, not the doc 🤪 will add it

Is the double-highlight a problem? Should we make the ref not highlighted?

[SuperOleg39]

:))

Is the double-highlight a problem? Should we make the ref not highlighted?

It will be nice, but is it technically possible?

Ideally, we need to highlight only pressed sidebar, but what we need to highlight after page reloading, for example?

Or if we highlight only source document link everytime, UX will be weird to.

Maybe you have a better and simple solution?)

[slorber]

Ideally, we need to highlight only pressed sidebar, but what we need to highlight after page reloading, for example?

Hmm I don't think there's much we can do here, we don't really want to persist click state or whatever, and just use current URL + link target to do the highlighting.

Probably complex to solve for little value, will not work on this but if it's important you can open a dedicated issue

[SuperOleg39]

Thanks you for helping!

Agreed that there is no simple solution, so I think no need to open new issue, we always can restructure our sidebar)

[SuperOleg39]

Sorry, one more thig.

Try MDX partial - have problem with content duplicates.

What about type: ref translations? Looks like docusaurus don't have this opportunity now?

I can modify this PR, and change translateDocs to translateRefs :)

[slorber]

Try MDX partial - have problem with content duplicates.

I don't understand what you mean.

What about type: ref translations? Looks like docusaurus don't have this opportunity now?

I can modify this PR, and change translateDocs to translateRefs :)

refs should be translated already by translateSidebar, which translate links (refs and docs are both links)

[SuperOleg39]

I don't understand what you mean.

If i use one documentation file as partial in two different docs, search will find same content at both of it

refs should be translated already by translateSidebar, which translate links (refs and docs are both links)

As i can see at code and when debugging, doc and ref are not translated in https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-content-docs/src/translations.ts#L154

If it works for docs, this PR would not be needed initially)

[slorber]

If i use one documentation file as partial in two different docs, search will find same content at both of it

Yes, the same content exist on 2 separate routes

As i can see at code and when debugging, doc and ref are not translated in https://github.com/facebook/docusaurus/blob/main/packages/docusaurus-plugin-content-docs/src/translations.ts#L154

Indeed it seems you are right: we can only translate categories and link items, not doc/ref labels.

But I don't understand why it's relevant for your use-case though: if you can add a custom label to each sidebar doc/ref, you don't really need to use the i18n support to customize the labels.

I can modify this PR, and change translateDocs to translateRefs :)

In this case, this is not what should be done. What should be done is to complete the translateSidebar implementation to handle the missing doc/ref type (only if a custom doc/ref sidebar label is provided).

My code shouldn't be uncommented, it's a different use-case.

[SuperOleg39]

But I don't understand why it's relevant for your use-case though: if you can add a custom label to each sidebar doc/ref, you don't really need to use the i18n support to customize the labels.

But how i can add different labels to different translations?

For example, here is default locale ref in sidebars.json:

{
  "type": "ref",
  "label": "Интеграция с tramvai",
  "id": "references/modules/router"
}

For en locale, and others, i stil need to have one common sidebars.json

[slorber]

Oh I see 😅 forgot that you had doc/ref AND en/ru.

So yes, the impl of translateSidebar should be completed to handle doc/ref (not what this PRR does).

Do you want to work on it?

[SuperOleg39]

Yes, be cool to implement this feature)

I'm just open a new PR later.

Do you have some advice about implementation, maybe test cases?

[slorber]

Thanks, waiting for your PR.

You have to complete getSidebarTranslationFileContent and translateSidebar to support doc/ref labels + add tests for this. Only items with a custom label should be in the translation file content (not all doc/ref items).

I can't really help more, otherwise it'll be faster for me to implement this myself 😅