nodejs
Select and Integrate an i18n Library
Summary
The @nodejs/i18n team is working to publish website / API docs translations to a node module from CrowdIn for us to consume. We need a way to integrate with these JSON translation files with the Gatsby site.
Basic example
https://www.gatsbyjs.org/blog/2017-10-17-building-i18n-with-gatsby/
Motivation
i18n infra is a basic requirement for widespread adoption.
Recently I have been doing research for a personal project where I am using gatsby as well. I conclude the following:
- For building the routes per locale there are two main gatsby plugin gatsby-plugin-i18n and gatsby-plugin-intl.
- For word formatting; to my understating, there is no out of the box practice, most devs choose between react-intl and i18next.
Note: for building routers, both plugins mentioned above do it by overriding createPages function in the gatsby-node.js. which seems a very similar practice currently used in the nodejs.org check the build.js file.
More precisely look at this snippet, where for each locale/lang the fullBuild function calls buildLocale.
Lastly, I have one concern about the mentioned practice, which is the build time, given the total number of pages to be built is NumberOfLangs*NumberOfPages. It may be an issue if the website is expected to be regularly updated.
I would be happy to help in developing this, as soon as the team reaches a consensus.
@benhalverson yes, I am happy to work on it. Any thoughts on which direction I should follow?
I would start with the gatsby plugins you mentioned and try to load the markdown files with the i18n lib that @zeke created here https://github.com/nodejs/i18n/pull/250 I think we should follow the way the current nodejs.org is setup if possible. ie https://nodejs.org/en/ https://nodejs.org/de/ etc
@benhalverson currently, when clicking on documentation, the site redirects to nodejs.org, it should stay on the same site on my edit given I will be pulling the markdown from Zake's module. right ?
Yes right now since the new docs are not ready so they redirect to the current docs. When the new docs are ready it will stay on nodejs.dev/docs
@benhalverson, sorry for lag between inquiries. Been busy lately.
Should we renders all doc for all versions or only for the supported versions which are specified in the package.json
https://github.com/nodejs/i18n/blob/cb96a168c33729c54a5374cab2a55c528fbabe07/package.json#L5-L9
Also, another important question(s), considering the following:
When the new docs are ready it will stay on nodejs.dev/docs
The current structure layout of nodejs.dev/docs only supports the api docs, i.e. and it assume each api is categorized in specific category i.e. classes, misc..etc (as shown in this snippet) https://github.com/nodejs/nodejs.dev/blob/b1ab6d2a2d7ba81b551bc48243eb9a098d81b06f/src/hooks/useApiDocs.tsx#L86-L93
However the new documentation (nodejs/i18n) seems to have totally different structure, where the documentation is divided into folders/files, i.e. doc/api/example.md, doc/guides/example.md, or doc/example.md..etc (per locale/per version)
Check content folder in i18n for reference.
That being said, how should I move forward, should I parse only the api/doc or everything?
Finally, I guess the docs page at pages/docs.tsx. needs to be modified and to be used as template instead. Also, its structure/layout needs to be changed to adopt the new documentation structure (depending on the decision of the above question) .
An update: regarding my previous comment :point_up:. Gatsby's team recently released i18n theme that we could use, or at least worth to check out.
Regarding my last inquiry can anyone help me or redirect to slack channel where the question is relevant.
Going to take this over and merge altogether with the i18n PR. The i18n theme seems to do exactly what we need for the localised markdown files!.
