i18n for guides

[vi-nastya]

Deployed version: https://mdr-ci.staging.k6.io/docs/refs/pull/211/merge/es

Describe changes
This pull request adds setup for translating the guides section.
For now language toggle is hidden and Spanish pages are hidden from algolia search, sitemap and sidebar.

How to add translations
For .md files:

• create a file inside src/data/markdown/translated-guides/es with the same relative path and file name as the english version (e.g. for getting-started/installation page we should have .../01 Getting Started/02 Installation.md withing both .../translated-guides/en and .../translated-guides/es folders)
• set frontmatter title to the Spanish title of the page. It would be used for generating localized slug, sidebar and SEO title.
• make sure that src/i18n/path-translations.js contains Spanish translations for all folder names without leading numbers (e.g., to generate ES pages for files located in .../es/02 Using k6/ folder we need to translate Using k6 key)

For top-level Guides page:

• translate all keys in ES section of src/i18n/guides-translations.js (Please note that now only Quickstart, Features and Use Cases sections support keys, will add the rest when the content is ready).

How to enable all i18n logic
Open config file at src/i18n/i18n-config.js. There are 4 flags:

• set disableRedirectToSelectedLanguage: false to enable redirecting to translated version in selected language
• set hideEsFromAlgoliaSearch: false to start sending ES content to Algolia for indexing and enable searching it
• set hideLanguageToggle: false to show language toggle on guides pages and remember language selected by user
• set hideEsFromRobots: false to remove noindex from ES pages

How it works

• Translating md files
  md files for Guides section are moved to markdown/translated-guides folder. They are now processed separately from other docs files. Inside markdown/translated-guides there are separate folders for each language with the same file structure and naming inside. We need the same file and folder names to find corresponding translations for each page. For localizing URLs we use title from frontmatter for file names and utils/path-translations.js files for folder names. Accents and special characters are replaced with latin characters.

• Translating top-level guides page
  Content for this page is translated using global context, that stores translations for each key (e.g. see src/components/pages/doc-welcome/quickstart/quickstart.component.js)

• Language toggle
  Language toggle is located in the sidebar and is only visible on Guides pages. The selected language is saved to the localStorage. After user chooses a language, when they open a link that has a translation in selected language, they will be redirected to the translated version (e.g. user selected ES => user clicks of EN slug of a page that has ES translation => user will be redirected to ES version of the page).

Steps to test

1. Pull the changes
2. Run npm i
3. Start the project in development mode, npm start
4. Follow http://localhost:8000/es, then any other page from sidebar or breadcrumbs or guides page.
5. Confirm that everything looks and works as expected

TODO

• add language change controls
• add SEO meta tags
• remove /en prefix for english guides links
• highlight selected page in sidebar
• update redirects for guides section
• change top level Guides link based on selected language
• update language control design and add mobile version
• hide language toggle visible only on guides pages
• add translated content
• make sure translated pages have title and description (SEO)
• replace special characters in URL
• make sure that Algolia search work with translated pages
• hide translated pages from Algolia search
• add NOINDEX for /es/* pages
• remove /es/* pages from sitemap

[ppcano]

@simskij do you know how can we fix Vale for the ES translation?

[simskij]

@ppcano

@simskij do you know how can we fix Vale for the ES translation?

There is no really good way of doing this as vale uses unix globs and not regex, but I managed to come up with a hack that solves it for now at least:

https://github.com/k6io/docs/blob/8901578e8ce155afc873d2660a3ede83e5d4d7fb/package.json#L20

Switch this command to instead run vale --glob='**/{docs,translated-guides/en}/**/*.md' ./src/data/markdown.