the footnote label "Footnotes" should be able to be translated

tats-u commented 10 months ago

Have you read the Contributing Guidelines on issues?

[X] I have read the Contributing Guidelines on issues.

Prerequisites

[X] 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

By the upgrade of the MDX plugin, the border of the document body and the footnotees has been changed from <hr> to the English-fixed heading. I couldn't find a way to change the language of the heading.

Some remark and related plugins can customize the "Footnotes" label by the option passed to mdast-util-to-hast.toHast.

https://github.com/remarkjs/remark-rehype#fields https://github.com/remarkjs/remark-rehype#example-footnotes-in-languages-other-than-english https://github.com/remarkjs/remark-html#options https://github.com/syntax-tree/mdast-util-to-hast#footnotes https://github.com/micromark/micromark-extension-gfm-footnote#label

Reproducible demo

WIP

Steps to reproduce

Set the language of your document as other than English
Add a footnote to a page in docs
docusaurus start
Open the page in your browser

Expected behavior

The footnote label is that in the language of your language (e.g. "脚注" in Japanese)

Actual behavior

Always "Footnotes" regardless of your language

Your environment

Public source code: WIP
Public site URL: WIP
Docusaurus version used: 3.0.0
Environment name and version (e.g. Chrome 89, Node.js 16.4): Firefox
Operating system and version (e.g. Ubuntu 20.04.2 LTS): Windows 11

Self-service

[ ] I'd be willing to fix this bug myself. ↑ If easy to fix, but doesn't seem

tats-u commented 10 months ago

We have to read defaultLocales and locales in docusaurus.config.* from processor.ts and pass correct MDX options to gfm in response to these Docusaurus config values.

slorber commented 10 months ago

cc @wooorm can we pass footnoteLabel option to remark-gfm?

It doesn't look to be supported atm in remark-gfm and micromark-gfm (outside of gtmHtml). Is there a high-level option to configure it easily?

@tats-u until we solve it, I think you can translate it in userland thanks to a rehype plugin

wooorm commented 10 months ago

remark-rehype has the options. Should be in both projects' docs!

slorber commented 10 months ago

Thanks!

Ref: https://github.com/remarkjs/remark-rehype#example-footnotes-in-languages-other-than-english

So it looks like a possible solution:

compile(
  {value: '…'},
  {remarkRehypeOptions: {footnoteLabel: 'Fußnoten'}}
)

I guess we could expose the whole MDX option object and deep merge it for maximum flexibility (although it expose the ability to break things? 🤔 ), or eventually just the remarkRehypeOptions option

tats-u commented 10 months ago

remark-rehype has the options. Should be in both projects' docs!

So it looks like a possible solution:

This is it. I have noticed it too several days ago but forgotten to tell it to correct my misuses guess. I am sorry for that.

I wonder if we should generate processor instances (the return value of (import ("mdx-js/mdx")).createProcessor) for each language.

https://github.com/facebook/docusaurus/blob/17c93e444ecedf09eb567709207f32213df88d15/packages/docusaurus-mdx-loader/src/processor.ts#L159-L169

Shall we add an additional argument language: string to createProcessorFactory? It is going to be transformed to a footnote label for the language that it presents. The most simplest transformer is a hashmap (lazy initialization may be needed).

    const processorOptions: ProcessorOptions & Options = {
      ...options,
      remarkPlugins,
      rehypePlugins,
      remarkRehypeOptions: {
        // this function translaveFootnoteLabel must be defined at another place by ourselves
        footnoteLabel: translateFootnoteLabel(language),
      },
      providerImportSource: '@mdx-js/react',
    };

slorber commented 8 months ago

PR to track: https://github.com/facebook/docusaurus/pull/9674

tats-u commented 8 months ago

It would be the best if the translated footnote label strings were out of the box.

tats-u commented 8 months ago

Can we use process.env.DOCUSAURUS_CURRENT_LOCALE in packages/docusaurus-mdx-loader/src/processor.ts? If so we will be able to prepare default footnote labels easily.

slorber commented 8 months ago

It would be the best if the translated footnote label strings were out of the box.

Agree, not sure where to store those translations though, maybe we could rename the docusaurus-theme-translation to just docusaurus-translations and put some default core translations there in a core.json file? 🤔

Our problem is that we probably want external contributors to find and translate those strings, and introducing another folder to translate is not going to help.

Can we use process.env.DOCUSAURUS_CURRENT_LOCALE in packages/docusaurus-mdx-loader/src/processor.ts? If so we will be able to prepare default footnote labels easily.

I'd prefer to pass the locale as mdx loader parameter instead of relying on this env variable for now. It's more explicit and testable.

But if we store translations there, who will be responsible to translate those strings?

cc @wooorm, any interest to maintain an official repo with footnote label translations? 🤪 I guess other MDX-based projects could benefit from this.

wooorm commented 8 months ago

It’s not specific to MDX, it’s more a GFM markdown thing. I can also see other websites wanting different labels. This value is what GH uses but on your own blog something else might be better.

Now, docusaurus probably already has certain other values that it translates, to me this is a better place to maintain and configure this?

slorber commented 8 months ago

@wooorm yes we have other values that we translate, and it makes sense to let site owners decide on the final label they want for their site.

However providing localized labels out of the box as a fallback would be convenient for the whole community. But it would remain the responsibility of individual projects and users to override those fallback labels if they are not good enough.

wooorm commented 8 months ago

Just feels weird setting up an i18n system in micromark-extension-gfm-footnote or mdast-util-to-hast where folks can PR different files, say i18n/pt.js and such, and other folks use one key "label" from there. Perhaps also needs a template language and to deal with plurals for backlinks?

That doesn't feel very "out of the box" for me.

facebook / docusaurus