Internationalization?

[nshiab]

The more I use Framework for my data analysis work, the more I feel it would be an excellent fit for documentation, too.

But is there any easy way to display/organize content in multiple languages?

Just an idea! :)

[Fil]

We're using Framework to document Framework, and my absolutely unbiased opinion is that it's a very nice experience.

There's admittedly not much yet in the area of plurilinguism—it can only improve (using lang, dir, connecting translations, etc.). I think however that this type of use case —like blogging (#1199)— will have to be chiefly driven and developed by the user community. (You're welcome to use this discussion board to share your experiments and define what might be needed to make progress.)

[nshiab]

This sounds like a fun and exciting challenge. I'll test a few things. :)

[nshiab]

A quick first test for French and English, just by playing with the observablehq.config.ts.

You can see it here: https://github.com/nshiab/framework

Here are the steps I took:

1. I created docs/en/ and docs/fr/ folders and populated them with a few files.

2. We need to keep docs/index.md, so I modified its content to redirect the user to a default language.

3. I changed pages in observablehq.config.ts to include pages in all languages:

pages: [
    // ENGLISH
    {name: "Hi!", path: "/en/index"},
    {
      name: "Examples",
      pages: [
        {name: "Example 1", path: "/en/example-1"},
        {name: "Example 2", path: "/en/example-2"},
        {name: "Example 3", path: "/en/example-3"}
      ]
    },
    // FRENCH
    {name: "Coucou!", path: "/fr/index"},
    {
      name: "Exemples",
      pages: [
        {name: "Exemple 1", path: "/fr/example-1"},
        {name: "Exemple 2", path: "/fr/example-2"},
        {name: "Exemple 3", path: "/fr/example-3"}
      ]
    }
  ]

3. I changed header in observablehq.config.ts to add a language picker:

header: `
<div style="display: flex; flex-grow: 1; align-items: center; justify-content: space-between; white-space: nowrap;">
    ...
    <span style="display: flex; align-items: baseline; gap: 1rem;">
      ...
    <select id="select-language">
      <option>en</option> 
      <option>fr</option>
    </select>
    </span>
  </div>

4. I changed footer in observablehq.config.ts to add a script that retrieves the language from the URL, cleans up the sidebar and adds an event listener on the language picker to redirect the user.

footer: ({path}) =>
    `<div>© ${new Date().getUTCFullYear()} Observable, Inc.</div>
    <script>

      // Retrieve the current language from the path
      const lang = "${path.split("/")[1]}"

      // Set the language select to the current language
      const selectLanguage = document.getElementById("select-language");
      selectLanguage.value = lang;

      // If the user selects a new language, we modify the path and redirect
      selectLanguage.addEventListener("change", (event) => {
        window.location.href = "/" + event.target.value + "/" + "${path.split("/").slice(2).join("/")}"
      });

      // Retrieve all languages from the select, except the current one
      const allLangs = Array.from(selectLanguage.options).map(option => option.value).filter(d => d !== lang);

      // Remove links from the sidebar that are not pointing to the current language
      for (const l of allLangs) {
        document.querySelectorAll('#observablehq-sidebar ol .observablehq-link').forEach(link => {
          if (link.querySelector("a").getAttribute('href').includes('/' + l + '/')) {
            link.remove();
          }
        });
      }

      // We remove empty sections
      document.querySelectorAll('section').forEach(section => {
        if (!section.querySelector('ol') || !section.querySelector('ol').children.length) {
          section.remove();
        }
      });
    </script>`

5. I set pager to false in observablehq.config.ts because my code doesn't handle it.

Pros:

• It was pretty easy for me to do! There was no need to dive into the Framework source code, as I wasn't sure where to start.

Cons:

• docs/index.md is empty and just redirects. It's probably not good for SEO.
• We are not changing and relying on the lang attribute.
• We don't handle the pager.
• It would be better to do all of this at build time.

What do you think @Fil ?

[Fil]

For the pager: “Pages and sections may also have a pager field which specifies the name of the page group”. So you could have one pager for "fr" and another one for "en", by adding these options in the pages configuration element.

[nshiab]

For the pager: “Pages and sections may also have a pager field which specifies the name of the page group”. So you could have one pager for "fr" and another one for "en", by adding these options in the pages configuration element.

Ah! Very nice. I updated pages. The pager now works.

pages: [
    // ENGLISH
    {name: "Hi!", path: "/en/index", pager: "en"},
    {
      name: "Examples",
      pager: "en",
      pages: [
        {name: "Example 1", path: "/en/example-1"},
        {name: "Example 2", path: "/en/example-2"},
        {name: "Example 3", path: "/en/example-3"}
      ]
    },
    // FRENCH
    {name: "Coucou!", path: "/fr/index", pager: "fr"},
    {
      name: "Exemples",
      pager: "fr",
      pages: [
        {name: "Exemple 1", path: "/fr/example-1"},
        {name: "Exemple 2", path: "/fr/example-2"},
        {name: "Exemple 3", path: "/fr/example-3"}
      ]
    }
  ],

Do you think pages could be specified as an array (like now) or a function to behave like head and footer ?

If it could be specified as a function receiving the path, users could customize the sidebar of each page. This would be handy for multilingual projects (there would be no need for the cleaning function in the footer) and probably for other things too. And it would be a non-breaking change.

Would it be difficult to do?

[nshiab]

I think I managed to do it!

See here: nshiab@5c5603f

I changed config.ts so pages can accept a function, and I exported normalizedPages because we will need it later.

I changed pager.ts to check whether pages is a function. If a function, we trigger it with the path as an argument, and we normalize the output.

I changed render.ts for the same reasons to render of the sidebar.

And it looks like it works!

What do you think @Fil ? Should I create a PR?