Request for I18N support

[brsvh]

I am willing to translate a Simplified Chinese rendition of pertinent documents, and while simultaneously keep a continuous watching over this repository. Could you create or initialize the foundational template for multilingual support on the website?

[brsvh]

If you are inclined to initiate the aforementioned support and employing git for the management of translations, there are some potential tasks:

• run npm run write-translations -- --locale zh-Hans to generate code.json for site
• copy existed docs to i18n/zh-Hans/docusaurus-plugin-content-docs/current
• add zh-Hans to supported locales in docusaurus.config.js

[srid]

@brsvh How would this look for submodule docs which live in other repos?

[brsvh]

About these documents originating from the upstream, I am uncertain about the recommended pratice of action (here and subsequently, I shall refer to the modules under the ext directory as the upstream).

I perceive two potential approaches, contingent upon the location of maintaining the multilingual versions of the documents. The first approach involves maintenance at the upstream, wherein it appears that the documents at the upstream ought to have been configured to utilize Docs Multi-instance.

By doing so, it becomes plausible to fetch the documents from the upstream and contribute multilingual documents to the repository upstream. Taking the documentation of haskell-flake as an example, one could envision contributing revisions akin to the following:

haskell-flake/doc/index.md
  move to haskell-flake/doc/en{,_US}/index.md
        & haskell-flake/doc/zh_CN/index.md

Subsequently, using a configuration like the following in docusaurus.config.js:

plugins: [
    [
      '@docusaurus/plugin-content-docs',
      {        
        path: '/',
        routeBasePath: '/',
        sidebarPath: require.resolve('./sidebars.js'),
      },
    ],
    [
      '@docusaurus/plugin-content-docs',
      {
        id: 'haskell-flake',
        path：'/ext/haskell-flake/doc/en',
        routeBasePath: '/haskell-flake',
        sidebarPath: require.resolve('./sidebarsYetAnotherOne.js'),
      },
    ],
  ],

In this manner, we can attain effortless maintenance by sustaining other languages in the form of symbolic links, much like the current usage. For instance, ext/haskell-flake/doc/zh_CN could link to i18n/zh-Hans/docusaurus-plugin-content-docs/current. I have yet to verify this method locally, but it is conceivable that maintaining the existing sidebar structure might pose a challenge.

The second approach involves establishing an overlay within this repository to maintain multilingual documents from the upstream source. I have simple implemented something locally:

npm run write-translations -- --locale zh-Hans
cp --recursive --dereference docs i18n/zh-Hans/docusaurus-plugin-content-docs/current/

Taking haskell-flake as an example, I proceeded to amend the examples.md document.

 slug: /haskell-flake/examples
 ---
 
-# Examples
+# 用例
 
 - [srid/haskell-template](https://github.com/srid/haskell-template/blob/master/flake.nix)

Simply run npm run start --locale zh-Hans, it is works.

[srid]

@brsvh I think I18N is still important. We're considering migrating the site, and use this opportunity to re-evaluate the tech choice. So we're not married to Docusaurus. Do you recommend any particular software (that is i18n friendly while supporting multiple sources) for the new website?

[brsvh]

The central question is where we want to maintain the multilingual resources, since the current documentation comes from a number of different github repositories. If we want to maintain it in the original repository, I know of few existing frameworks designed for that purpose.

[srid]

This repo will be broken down into two sites (and then archived on GitHub):

• https://github.com/flake-parts/community.flake.parts (docs for individual flake-parts modules)
• https://github.com/nixos-asia/website (the new NixOS Asia community)

The latter (which will contain everything but docs for individual flake-parts modules) assumes i18n structure from the get go.

[srid]

Done!

Come check out https://nixos.asia/en ... it uses Emanote, so we could probably also improve Emanote itself for better i18n @brsvh I'm happy to support that especially as "NixOS Asia" is inclusive of multi-language countries from get go.

I'll archive this repo now.