PaloAltoNetworks / PaloAltoNetworks/docusaurus-openapi-docs

i18n support

Open
#319 12 comments 2 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement help wanted
Dominant language
TypeScript
Stars
1.1k
Forks
315
Avg merge
7d 5h
Merged PRs (30d)
7

Description

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
Screenshot 2022-11-02 at 17 36 58

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by running docusaurus write-translations in a representative site and inspect the generated JSON, using the existing version.label entry as a baseline. Trace how the plugin's API documentation strings are exposed to Docusaurus translations; done means labels are generated for the listed headers, controls, buttons, and field labels.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
documentation, internationalization
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.