Translation for other languages optimizations

Several people have offered and written translations for our docs. While they do technically work, there are some optimizations that should be considered to make this process more seamless. This is a bit of a brain dump.

• https://github.com/cypress-io/cypress-documentation/issues/602
• https://github.com/cypress-io/cypress-documentation/issues/1327
• https://github.com/cypress-io/cypress-documentation/issues/1595

Algolia is only searching English docs.

I set up a new index for Chinese translations, but I don’t really know how to hook this up to the zh-cn pages for searching - https://github.com/cypress-io/cypress/pull/4208

Also, we could add some translations for the actual text shown within Algolia for searching instead of these words being static.

✅ Images are being copied over for every translation https://github.com/cypress-io/cypress-documentation/pull/1728

I don’t think it is ideal to duplicate the entirety of our images folder for each translation. This should be refactored somehow to live outside perhaps.

Some of the _data is being copied over for every translation

• source/_data/languages.yml
• source/_data/main-menu.yml
• source/_data/sidebar.yml

We don’t want to have to duplicate this every time we add a new file. This has no relevance to translation and will be the same for each language.

✅ Tests are not DRY https://github.com/cypress-io/cypress-documentation/pull/1703

Each language is now written independently for testing. We should probably loop through each available language and run the same tests for each to DRY this up.

Some of the links don’t go to a translated url https://github.com/cypress-io/cypress-documentation/pull/1735

• When clicking on ‘Plugins’ in the main menu, it always goes to the English page.
• Link to ‘edit’ doc doesn’t go to corresponding language dir
• Link to ‘prev’ and ‘next’ do not go to translated doc
• Links to API table of contents don’t go to translated doc

Whenever changes are made to the main English documentation - they need to be manually copied over to every language.

See https://github.com/cypress-io/cypress-documentation/issues/1795

This is the most time consuming and cumbersome part of the existing process. It would be great if there were an automated script that could take any commits made into the en docs - search the other language folders (like zh-cn), find the same doc files and add the new English into those docs automatically.

Also, adding entirely new doc files should be copied over to all language folders - (think for every new changelog)

Rather than duplicate the same english .md docs for the japanese and chinese languages - can we just handle this automatically at the build process level?

For instance, if a language is supported but does not yet have the translated docs - can it use the english ones by default?

I really don’t like the idea of duplicating these documents for each language - it has already caused problems and confusion and it will without a doubt continue to cause more issues.

See here: https://github.com/cypress-io/cypress-documentation/pull/1792

This is not sustainable. Instead we should write some build process code that automatically copies the english markdown files to the other language when generating the static site - but keep them out of source control.

Nobody is going to want to update X number of versions of (english) markdown documents for other languages - that’s complicated.

Alternatively we could even automatically create symlinks to the english files to backfill them (so they show up in the file tree).

✅ rtl text direction https://github.com/cypress-io/cypress-documentation/pull/1716

For Hebrew, support meta data rtl to display language right-to-left.

Partial tag

There is a problem in partial tag. In translation dir, the parital tag will include source/_partial, it should be source/zh-cn/_partial.

{% partial network_stubbing_warning %}

✅ is easy to just copy/paste in wrong content https://github.com/cypress-io/cypress-documentation/pull/1800

We had an incident where an English title on a page had a Chinese title incorrectly pasted in - (its easy to confuse the translated docs when searching for ‘configuration.md’ for example - since there are 3 results).

We should have tests to at least ensure that the title content in the h1 is the intended content from the translated page.

Optimize for SEO

• Implement these best practices so that Google recognizes translated pages as alternative translations: https://support.google.com/webmasters/answer/189077?hl=en&visit_id=637002396938016733-1976776371&rd=1
• This issue to include translations into Google search https://github.com/cypress-io/cypress-documentation/issues/1946

Table of Contents not highlighting active section for special characters

The table of contents does not highlight as active when the section title has special characters - see Russian and Chinese for example.

[RealLau]

@jennifer-shehane Hi, I realize that the new cypress-documentation directories have changed(e.g: there’s no source dir any more), can you update the guide line on how to set up a new language translation?

[jennifer-shehane]

@viraxslot I’m not sure, I haven’t looked at it at all. I’ll do some investigating today.