-
-
Notifications
You must be signed in to change notification settings - Fork 8.5k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
fix(plugin-content-docs): enable docs translations #5593
Conversation
Hi @SuperOleg39! Thank you for your pull request and welcome to our community. Action RequiredIn 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. ProcessIn 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 If you have received this in error or have any questions, please contact us at cla@fb.com. Thanks! |
✔️ [V2] 🔨 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 |
⚡️ Lighthouse report for the changes in this PR:
Lighthouse ran on https://deploy-preview-5593--docusaurus-2.netlify.app/ |
Thank you for signing our Contributor License Agreement. We can now accept your code for this (and any) Facebook open source project. Thanks! |
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 :) |
Note, I plan to introduce a docs plugin option callback |
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: Document source is here - https://github.com/TinkoffCreditSystems/tramvai/blob/main/packages/libs/router/README.md And for features, we want one Shor version of our dynamically created and untranslated
Without thist PR, we can translate only categories in And the question is how we can prodive two different |
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:
If you really want to use a single doc / route for this page, I'd recommend to use a 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) |
Going to close this because I believe there are better alternatives, but still open for discussion |
Thank you for interesting advices, 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) |
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 |
Just try to use
And
So maybe |
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? |
:))
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?) |
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 |
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) |
Sorry, one more thig. Try MDX partial - have problem with content duplicates. What about I can modify this PR, and change |
I don't understand what you mean.
refs should be translated already by |
If i use one documentation file as partial in two different docs, search will find same content at both of it
As i can see at code and when debugging, If it works for docs, this PR would not be needed initially) |
Yes, the same content exist on 2 separate routes
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.
In this case, this is not what should be done. What should be done is to complete the My code shouldn't be uncommented, it's a different use-case. |
But how i can add different labels to different translations? For example, here is default locale
For en locale, and others, i stil need to have one common sidebars.json |
Oh I see 😅 forgot that you had doc/ref AND en/ru. So yes, the impl of Do you want to work on it? |
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? |
Thanks, waiting for your PR. You have to complete I can't really help more, otherwise it'll be faster for me to implement this myself 😅 |
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
, becausecreateSampleDoc
don't create uniqueunversionedId
, andtranslateLoadedContent
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 ini18n/en/docusaurus-plugin-content-docs/current.json
Second,
docusaurus start --locale en
should respect translations incurrent.json
in sidebar and docs titleRelated 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.)