i18n support

[karjona]

Hello everyone, Currently, the plugin doesn't seem to generate much internationalization data when running docusaurus write-translations. Only a single i18n label appears to be generated, at least in my environment:

{
  "version.label": {
    "message": "Next",
    "description": "The label for version current"
  }
}

This makes it very difficult to translate API documentation generated by this plugin into different languages.

Is your feature request related to a problem?

• No

Describe the solution you'd like

Ideally, when generating translation data using docusaurus write-translations, the plugin would create i18n labels for every string that can be reasonably translated, as other plugins (including the built-in ones) already do. That would mean generating labels for, for example:

• Headers and table data in the intro doc
• Collapsible header titles in the endpoint docs ("Request", "Authorization")
• Buttons and other interactive elements ("Send API Request", "Example")
• Labels ("required")

The site owners could then localize these elements to the different languages they need for their site.

Describe alternatives you've considered

I've considered hiding the language select dropdown while browsing the API documentation or generating a new, separate docusaurus instance that only contains the API documentation, isolated from the rest of the more general docs that we currently provide in different languages. This can certainly be done, but it takes extra work to host and manage and makes our global documentation solution... less inclusive, for lack of a better word.

Additional context

[welcome-to-palo-alto-networks[bot]]

:tada: Thanks for opening your first issue here! Welcome to the community!

[sserrata]

Hi @karjona, thanks for reporting this issue! I am not too familiar with i18n and would appreciate any help you can provide. To start, can you explain how "labels" can/should be applied or point to an example? Thanks!

[selankon]

Hi, same necessity here.

Another question is how to write swagger with internationalization support (maybe using something similar to this?)

Probably faster solution could be related to integrate docusaurus-openapi-docs to give support to crowdin or similars

[karjona]

Hello everyone, To give a bit more context: when you run docusaurus write-translations, all supported plugins generate a .json file in the i18n folder of the docusaurus instance or update the code.json file in that same directory. The file contains all labels you can translate for that plugin and the description of where those labels are used.

For example, when running docusaurus write-translations on my instance that contains the @easyops-cn/docusaurus-search-local plugin, the code.json file contains the labels to translate all the strings related to the search box.

"theme.SearchBar.noResultsText": {
  "message": "No results"
},
"theme.SearchBar.seeAll": {
  "message": "See all results"
},
"theme.SearchBar.label": {
  "message": "Search",
  "description": "The ARIA label and placeholder for search button"
},

You can then use these labels to translate the site. This same feature would be great for the API docs. Generating these labels for "required", "Requests", "Responses", etc. would be great.

[sserrata]

Thanks @karjona, I believe I identified how this is being done:

Lifecycle method: https://docusaurus.io/docs/api/plugin-methods/i18n-lifecycles#getDefaultCodeTranslationMessages Example: https://github.com/easyops-cn/docusaurus-search-local/blob/master/docusaurus-search-local/src/server/index.ts#L38

We'll add this to our roadmap.

[selankon]

FYI crowdin integration breaks things with generated code. This is not a problem on docusaurus-openapi-docs , is crowdin application breaking thins on .mdx files

https://community.crowdin.com/t/broken-mdx-components-on-download/2912

https://community.crowdin.com/t/exclude-single-line-on-markdown-headers/2897

[alienzhangyw]

Any update?

[alienzhangyw]

I tried to wrap the text in theme components with <Translate></Translate> from @docusaurus/Translate, then ran docusaurus write-translations, and it worked.

[psztoch]

Once the translation mechanism is created, we can develop the Polish language.