Skip to content
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

Improve i18n DX to translate the _category_.yml labels #8996

Open
2 of 7 tasks
Ikalli opened this issue May 19, 2023 · 12 comments
Open
2 of 7 tasks

Improve i18n DX to translate the _category_.yml labels #8996

Ikalli opened this issue May 19, 2023 · 12 comments
Labels
domain: i18n Related to the i18n system proposal This issue is a proposal, usually non-trivial change

Comments

@Ikalli
Copy link

Ikalli commented May 19, 2023

Have you read the Contributing Guidelines on issues?

Prerequisites

  • I'm using the latest version of Docusaurus.
  • I have tried the npm run clear or yarn clear command.
  • I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
  • I have tried creating a repro with https://new.docusaurus.io.
  • I have read the console error message carefully (if applicable).

Description

I am currently internationalizing (i18n) a document written in Korean into English.

The sidebar of my document is all autogenerated sidebar.

// sidebar.js

/** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */
const sidebars = {
  // By default, Docusaurus generates a sidebar from the docs folder structure
  exampleSidebar: [{ type: 'autogenerated', dirName: 'example-dir' }],
};

module.exports = sidebars;

I have copied the /docs subfolders originally written in Korean to /i18n/en/docusaurus-plugin-content-docs and I am translating the documents into English. However, even if I change the label attribute in /i18n/en/docusaurus-plugin-content-docs/example-dir/under-example-dir/_category_.yml to English, it continues to appear in Korean in the sidebar.

# /i18n/en/docusaurus-plugin-content-docs/example-dir/under-example-dir/_category_.yml
position: 2
label: 'Example'
collapsible: true
collapsed: false
# /docs/example-dir/under-example-dir/_category_.yml
position: 2
label: '예제'
collapsible: true
collapsed: false

I run docusaurus following step:

  1. yarn dev --locale en

But in example-dir sidebar, it displays Korean, not English.

I already wrote about this in #8986

Reproducible demo

https://github.com/dogu-team/dogu-docs

Steps to reproduce

  1. Clone or fork https://github.com/dogu-team/dogu-docs this repository and open
  2. Checkout branch to label_reproduce
  3. Enter yarn newbie
  4. Change docs/host-and-device/host/_category_.yml as
    position: 2
    label: '호스트'
    collapsible: true
    collapsed: false
  5. Check i18n/en/docusaurus-plugin-content-docs/current/host-and-device/host/_category_.yml. This should be
    position: 2
    label: 'Host'
    collapsible: true
    collapsed: false
  6. yarn dev --locale en or yarn build && yarn serve
  7. Go to http://localhost:3100/en/host-and-device/host/get-started and check sidebar.
  8. Sidebar label will still '호스트'(korean), not 'Host'.

Expected behavior

Sidebar label should be 'Host', not Korean

Actual behavior

Sidebar label shows '호스트', not English

Your environment

Self-service

  • I'd be willing to fix this bug myself.
@Ikalli Ikalli added bug An error in the Docusaurus core causing instability or issues with its execution status: needs triage This issue has not been triaged by maintainers labels May 19, 2023
@Lorde627
Copy link

Lorde627 commented May 27, 2023

I got the same problem here; I don't know if this is a bug or if the _category_.yml is not working here at the start.

@Josh-Cena
Copy link
Collaborator

Josh-Cena commented May 27, 2023

Hi! I18n does not use _category_ files, because that allows localized sites to have different sidebar structures which we don't want. If you want to translate the label, use yarn write-translations, and the sidebar labels should be generated in JSON.

@Josh-Cena Josh-Cena closed this as not planned Won't fix, can't repro, duplicate, stale May 27, 2023
@Josh-Cena Josh-Cena added closed: question This issue is a user error/misunderstanding. closed: working as intended This issue is intended behavior, there's no need to take any action. domain: i18n Related to the i18n system and removed bug An error in the Docusaurus core causing instability or issues with its execution status: needs triage This issue has not been triaged by maintainers labels May 27, 2023
@slorber
Copy link
Collaborator

slorber commented May 30, 2023

@Josh-Cena another person reported the same problem here: #8986

I think we can re-open and try to figure out how we can improve the UX/DX on this specific case to make the behavior more intuitive.

We already allow to partially translate front matter (SEO description etc) so I guess it could make sense to also allow partial translation of the _category_.yml file? 🤷‍♂️

@slorber slorber reopened this May 30, 2023
@slorber slorber removed closed: question This issue is a user error/misunderstanding. closed: working as intended This issue is intended behavior, there's no need to take any action. labels May 30, 2023
@slorber slorber changed the title _category_.yml label with i18n not working Improve i18n DX to translate the _category_.yml labels May 30, 2023
@slorber slorber added the proposal This issue is a proposal, usually non-trivial change label May 30, 2023
@Lorde627
Copy link

@Josh-Cena another person reported the same problem here: #8986

I think we can re-open and try to figure out how we can improve the UX/DX on this specific case to make the behavior more intuitive.

We already allow to partially translate front matter (SEO description etc) so I guess it could make sense to also allow partial translation of the _category_.yml file? 🤷‍♂️

That will be awesome!
It would be fantastic if i18n (internationalization) could offer greater customization, allowing for the modification of navigation bar or footer jump buttons based on the locale. For instance, if the jump button for the English locale redirected to https://google.com/, the Japanese locale could redirect to https://google.jp/. Implementing such a feature would greatly enhance the overall user experience.

@slorber
Copy link
Collaborator

slorber commented May 30, 2023

@Lorde627 what you describe here is a totally different problem: let's not discuss all i18n issues here.

I shared a temporary workaround on how to use different Docusaurus site configs on a per-locale basis: #4542 (comment)

This is not an ideal API/DX but it allows you to customize title/tagline/navbar/footer per locale.

@Josh-Cena
Copy link
Collaborator

Josh-Cena commented May 30, 2023

@slorber To me it sounds inconsistent to have a 3rd way to translate content. We already have the model of "Markdown + JSON" and there are relatively few places to look for for translated text. Now we will have to deal with priorities (because the JSON is always going to be emitted anyway; write-translations doesn't know where the sidebar data is coming from). In addition we probably don't want to allow a different sidebar position option for localized sidebars, so there's still glaring inconsistency.

If our goal for this issue is only to "improve DX", the only option I feel comfortable with is emitting a warning message if we find _category_ files in localized folders.

@slorber
Copy link
Collaborator

slorber commented May 30, 2023

Let's keep it open for now, need to think about it a bit more 🤪

The thing is, I'd like to make it possible to translate content by using localized file extensions. Many other docs solutions do this and it's more convenient in many cases:

  • docs/myDoc.mdx
  • docs/myDoc.fr.mdx
  • docs/myDoc.it.mdx

If we implement this but do not allow to translate category labels directly through the docs folder, that will be even more frustrating for users.

For example Nextra: https://nextra.site/docs/guide/i18n#use-add-locale-to-filenames

/pages
  _meta.en.json
  _meta.zh.json
  _meta.de.json
  index.en.md
  index.zh.md
  index.de.md
  ...

The _meta.json API is quite different though: https://nextra.site/docs/docs-theme/page-configuration

@Ikalli
Copy link
Author

Ikalli commented May 31, 2023

Finally I found the solution for autogenerated sidebar with i18n:

  1. Change _category_.yml to _category_.json
  2. After yarn write-translations, translations for sidebar labels will be added to the i18n/[locale]/docusaurus-plugin-content-docs/current.json file.
  3. In _category_.json, update label property to translate key.
    • For example,
    {
      "label": "sidebar.foo.category.bar"
    }

Also, I couldn't find any information on the autogenerated sidebar documentation page about not being able to use i18n functionality when using _category_.yml, but it is possible when using _category_.json. For now, updating the documentation or emitting CLI warning message to improve DX could be good solutions.

@Josh-Cena
Copy link
Collaborator

I'm surprised by steps 1 and 3 in your workaround! That's not how I understand translations work at all. We would need to look into this; maybe there actually is a bug.

@Ikalli
Copy link
Author

Ikalli commented May 31, 2023

Ohh... I see.🥲 Then is there any solution to apply "working on the right way" translations to autogenerated sidebar labels? I couldn't find some examples for this. Or, configuring sidebars in sidebar.js is the only way for i18n?

@yujingz
Copy link

yujingz commented Sep 25, 2023

Ohh... I see.🥲 Then is there any solution to apply "working on the right way" translations to autogenerated sidebar labels? I couldn't find some examples for this. Or, configuring sidebars in sidebar.js is the only way for i18n?

second this, the official documentation did not mention this part at all

@Josh-Cena
Copy link
Collaborator

When you run yarn write-translations, all sidebar labels, including those in _category_.json, should be emitted. We do this on our own website and it looks like they are successfully translated.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
domain: i18n Related to the i18n system proposal This issue is a proposal, usually non-trivial change
Projects
None yet
Development

No branches or pull requests

5 participants