i18n initiative documentation

[sheplu]

Most of the language and framework now have a documentation translated in multiples languages allowing newcomers an easier / simpler way to onboard with the language.

Node.js seems to be on of the top technology not having that (I will provide an updated list on technologies and framework) and I think it would be nice to provide this functionality on the documentation

There is currently a crowdin with allow people to provide translation in a good / easy way but I don't think this is included on the new website initiative / new changes (I will check)

It could be great to discuss about that in a later meeting

• do we want to provide that?
• if yes which language
• how we want to do it
• on which part

[ovflowd]

Hey there, @sheplu 👋 , indeed Crowdin is not included in the new Website initiative. I would love to sync with you regarding what you need from our side to make it work, or even what the options would be.

[sheplu]

hello @ovflowd ! I opened the issue mostly to start a discussion about i18n for some/all resources regarding Node.js. I don't really have a preferred tool but mostly would like to see if we want (I think that could be great) to work on this topic

I am not sure who is running the crowdin or if there is some activity on this part but we can talk about it and try to see what we can all do !

[ovflowd]

Would love to talk, I'm on Slack 🙃

[ovflowd]

Meeting notes:

Different kinds of Documentations

We discussed that what we understand as "documentation" is a collection of living documents that embrace three different primary embodiments, those are:

• API Docs: A bare-bone visual representation of the specifications of the set of APIs exposed by Node.js. From classes, modules, functions, constants and more. These primarily should be auto-generated.
  • One of the ideas here is to pick the source from the JSDocs directly. (Idea!)
  • Simple examples and descriptions are provided within jsdoc
  • Snippets are a pure code-only snippet
  • Descriptions can be translated through locale files
• Node.js Docs: Actual human-focused documentation about the modules that Node.js provides
  • Actual Markdown files (MDX) that describe and guide through each Module of Node.js
  • Separated by categories, where each page is about a module. (Idea)
  • Pages have tags that are handy for when searching for content
  • Each page explains what this module is about, what it does, and gives examples and repl.it (Live snippets that users can play around)
  • These docs get versioned per Node.js release (Idea)
  • eg.: content/docs/16/fs.md
  • This allows examples and functionalities of that module to be introduced and explained by relevance (Eg.: v18 introduced XX on fs)
  • Each doc has an introduction section independent of the Node.js release. (Idea)
  • Allows a generalised introduction
  • Docs pages have a table of contents
• Learn & Guides: These are guides that introduce you to the Node.js world
  • Learning guides are separated into sections "What is Node.js", "Getting started", "Introduction", ....
  • Learning guides explain real-world scenarios for what you can do with Node.js, eg.: "How to make a web server", "How to read & write files", "What is NPM"
  • Each page also has tags that allow easier indexing/search
  • Learning guides focus on introductory and essential guides for the Node.js world. They might also enter the world of some more intermediary examples, but the idea behind these guides is to give you an insight into what you can do with Node.js; they're not meant to be actual courses or deep-dive learning materials.
  • Learning guides are not-versioned and should resemble the state-of-art of Node.js

How we provide Documentation

Interestingly, creating such Documentation standards is a no-easy task. Generating the API Docs and rendering them into a Website (in a format that is accessible, localised and easy to search and navigate) is the bare-bones of requirements. Yet, these are easy once a standard is defined (e.g.: generating from jsdoc).

Creating Node.js Module Documentations (Node.js Docs) requires contributor effort from migrating from the current docs provided in the API docs to content that suits such section and is a long-term effort.

• Indexing the content and making it available (Currently working on nodejs.dev)
• Able to create custom labels for each page (Needs Refinement)
• Support current Docs from node/docs/api (In Progress on nodejs.dev)
• Localisation of Learn guides and Node.js Docs (Currently working on nodejs.dev)
• Generation of API Docs from jsdoc (Needs significant discussion with Docs/Build/Release team)
• Definition of Specification/Standard for Docs in the future (Needs significant discussion with Docs/Build/Release team)

[sheplu]

thanks a lot for the full meeting note @ovflowd :) it was really great talking to you ! I will try to join for the next meeting around nodejs.dev as a lot of works seems to be already in progress.

[sheplu]

This issue as been open for a long time. I am currently checkout github action capabilities on how we could automatically keep localized doc up to date with the main one (in english) and allow local team to work on it.

I should have a working demo end of january

[ruyadorno]

Action items from the Apr 12 meeting:

• Let's define some concrete goals that a language translation would need to achieve in order for the project to support that language (percentage of docs translated, number of collaborators supporting that translation, etc)
• Define a champion (might be an informal role) that will coordinate work on the translation for each specific language

[ovflowd]

I would probably recommend for this proposal to go not further as from prior experience with the TSC they will pretty much reject this.

[ovflowd]

Since I see that @AugustinMauroy is still working on this, I would strongly recommend for this proposal to be archived for the time being.

It was discussed in one of the TSC meetings that i18n within the API docs is a no-go, and I completely agree with that. Many reasons were given by TSC members such as @mcollina on why in general translating API docs is unsustainable and a bad practice. (cc @nodejs/tsc if anybody else from the TSC is interested on this issue)

@sheplu I'd consider closing this issue.

[ovflowd]

I also believe that this proposal got split into two (on what eventually became the "Metadata Proposal", which indeed is not "i18n" anymore).