Improve i18n DX to translate the _category_.yml labels

[Ikalli]

Have you read the Contributing Guidelines on issues?

• I have 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

• Public source code: https://github.com/dogu-team/dogu-docs/tree/label_reproduce
• Public site URL: https://docs.dogutech.io
• Docusaurus version used: 2.4.1
• Environment name and version (e.g. Chrome 89, Node.js 16.4): Node.js 16.16.0
• Operating system and version (e.g. Ubuntu 20.04.2 LTS): macOS Ventura 13.13.1 (a)

Self-service

• I'd be willing to fix this bug myself.

[Lorde627]

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]

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.

[slorber]

@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? 🤷‍♂️

[Lorde627]

@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]

@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]

@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]

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]

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]

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]

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]

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]

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.