locale-specific API docs?

[alexakreizinger]

👋 hey, thanks for maintaining Redocusaurus—I'm a big fan!

I have a somewhat unusual use case I'm trying to solve for with the docs site I manage, which has to do with Docusaurus's i18n feature and the different locales this feature generates. let me start off by describing what I want to achieve:

my goal: for users on different locales (e.g., en, fr) see different versions of the same API doc (e.g., Petstore API) depending on which site locale they're browsing (e.g., website.com/en/petstore-api/ vs website.com/fr/petstore-api/).

I don't mind maintaining two different YAML files if need be (e.g., petstore-en.yaml and petstore-en.yaml`); the main question I'm trying to solve right now is how to actually generate the docs pages in a way that's truly unique for each locale. there are two approaches I can think of, but both have their own issues—so if I can work around the issues in at least one approach, I'll be good to go 🙂

possible approach 1: auto-import docs via docusaurus.config.js

the standard auto-import approach is how I've been generating our API docs until now (before this whole locale thing cropped up :P). I really like this approach for its simplicity and for the actual output of the docs themselves—particularly the three-column layout—but I can't figure out how to make the imports correspond to a particular locale (or whether it's possible to do so). all specs seem to apply to all locales, and any routes are generated related to the default locale's URL.

for example, given a sample config file:

      'redocusaurus',
      {
        // Plugin Options for loading OpenAPI files
        specs: [
          {
            spec: './api/petstore.yaml',
            route: '/petstore-api',
          },
      }

if my docs site is website.com, this will auto-generate API docs at website.com/en/petstore-api and website.com/fr/petstore-api, but both APIs will be identical (which is to say, in English, since the YAML file itself is in English).

on the other hand, given a different (non-functional) sample config-file:

      'redocusaurus',
      {
        // Plugin Options for loading OpenAPI files
        specs: [
          {
            spec: './api/petstore-en.yaml',
            route: 'en/petstore-api',
          },
          {
            spec: './api/petstore-fr.yaml',
            route: 'fr/petstore-api',
          },
      }

but this snippet doesn't actually work the way I wish it did: it generates an English API for both the en and fr locales and a French API for both the en and fr locales, all with somewhat garbled URLs: website.com/en/en/petstore-api and website.com/fr/en/petstore-api for the first spec, and website.com/en/fr/petstore-api and website.com/fr/fr/petstore-api for the second spec.

so, my question for this approach is whether it's possible to make these specs truly locale-specific 🤔 I'm not sure if that would mean, for example, having two redocusaurus objects in the docusaurus.config.js file (or how they'd be configured).

possible approach 2: manually import ApiDocMdx

I have a hunch this is the more feasible approach between the two: rather than using the auto-import style docs above, I could do something like the Nested Docs example and change the corresponding mdx file for each locale to import different OpenAPI specs.

for example:

[page in EN locale]

import ApiDocMdx from '@theme/ApiDocMdx';
<ApiDocMdx id="petstore-en" />
---
[page in FR locale]

import ApiDocMdx from '@theme/ApiDocMdx';
<ApiDocMdx id="petstore-fr" />

the only problem here (and it's an important one to me 😅) is that I wish these manually imported docs looked more like the auto-imported docs' three-column layout! even when I hide Docusaurus's innate left sidebar, these manually imported docs use a two-column layout (despite having plenty of whitespace available):

so, my question for this approach is whether it's possible to create a standalone page and manually import the corresponding OpenAPI spec for that page, but have the output look more like the auto-imported docs.

[rohit-gohri]

my question for this approach is whether it's possible to create a standalone page and manually import the corresponding OpenAPI spec for that page, but have the output look more like the auto-imported docs.

This is definitely possible if you create a react page, this is the output - https://redocusaurus.vercel.app/examples/custom-page/
And this is the source file - https://github.com/rohit-gohri/redocusaurus/blob/main/website/src/pages/examples/custom-page/index.jsx

I think you can make this page dynamic and load the correct yaml using docusaurus context ( https://docusaurus.io/docs/docusaurus-core#useDocusaurusContext )

const {i18n} = useDocusaurusContext();
const locale = i18n.currentLocale;

This would require specifying all yamls in the docusaurus context without the route option so yamls are available programmatically but route is defined by you using custom react pages

[alexakreizinger]

🤩 this looks like exactly what I need! I've definitely seen the output of that "Custom Page" doc before, but I had no idea it was generated via a JSX file.

(and thank you so much for the speedy reply 😁)

[bryanjtc]

@alexakreizinger Did you manually translate the yaml file or did you use a cli, service or plugin?

[alexakreizinger]

manually translated, in my case, so unfortunately I don't have any cool tools I can recommend for the job :(