Update or remove outdated / abandoned documentation translations

[jhildenbiddle]

Bug Report

The documentation translations available on docsify.js.org are outdated and in some cases completely abandoned. Inaccurate documentation in a preferred language is (IMHO) far worse than accurate documentation in a non-preferred language.

Last updated:

• docsifyjs/docs-es: 11/7/2023
• docsifyjs/docs-de: 4/23/2020
• docsifyjs/docs-ru: 4/23/2020
• docsifyjs/docs-zh: 8/28/2023

Without native language speakers to keep these translations up to date, it seems wise to consider the following options (ordered from most to least preferred):

1. Retire these translations altogether and rely on modern browser language translation features (see below).
2. Explore automated translation services to keep these repos up to date. GitLocalize is one free option worth considering.
3. Continue manually supporting only the translation(s) we can verify site visitors use and that maintainer(s) are willing to actively maintain.

IMPORTANT: At the time Docsify's documentation translations were created, browsers did not offer built-in language translation functionality. Today, all major browsers offer built-in language translation functionality. This means that non-native English speakers can visit our English docs and have them auto-translated to their native language by the browser automatically if they prefer.

Below are screenshots from taken while viewing docsify.js.org translations as an English-preferred visitor:

Chrome - 简体中文

Safari - Deutsch

Firefox - Spanish

[paulhibbitts]

Thanks for bringing this issue up @jhildenbiddle. As you've identified, up-to-date translation itself is a major on-going effort to create and then maintain - for example, another open source project I have been involved with is https://getgrav.org has a dedicated team of volunteer contributors using Crowdin https://crowdin.com/profile/getgrav.

The out-of-date docs is a major user experience issue in itself. Based on what I see, perhaps option 1 is a beneficial path to take for the initial release of v5 and then re-assess viability of either option 2 or 3? Interested to hear other perspectives.

[trusktr]

Browser translation is pretty good I think, especially after many years of improvements.

Does having pre-translated docs help with SEO? For example, do search engines show users in a nother country results for english sites in their language? Or do websites need to have content in the target country's language to become visible there?

If the answer is that pre-translation would be needed for this, I'd say maybe that's the single most reason to do it. But then the question would be how? And another question is, will keeping the current translations even if outdated help with this SEO?

[Koooooo-7]

I think we can keep the remained documentation translations, and add the last update date banner with docsify-top-banner-plugin. i.e

This label could be automate update, when new commits into.

Current site last update date is [xxxx-xx-xx] if you don't find the things you want, try find in latest [EN] site.

Browser translation is always available, every users can use it in our default update-to-date EN docs, if users can not find the target part in their prefer langs, they can go to the EN docs.

@trusktr mentioned the SEO thing is reasonable to me, and I think the Browser translation still exist the Gap for the natives.

[jhildenbiddle]

Our goal should be to provide accurate, useful documentation to Docsify users. If our translations don't do that, then they aren't serving their intended purpose and we should remove them for the benefit of our users and our project maintainers. It should be that simple.

I appreciate the desire to show translations on the site, but the reality is that offering localized content that serves users requires a significant upfront and continued investment that our team simply does not have the capacity to make. Pretending this is not the case by publishing inaccurate and/or outdated documentation that hasn't been updated since 2020 is a disservice to the site visitors that read those translations and, IMHO, reflects poorly on both the project and its maintainers.

As for SEO, I don't think there is any reason to believe our existing translations impact SEO primarily because docsify.js.org serves pages (including all translations) in router: hash mode which we know generates URLs that are not indexed reliably (if at all) by search engines.

Fortunately, we don't have to speculate about SEO. Our site is configured with Google Analytics so we can see exactly where our traffic is coming from and how many visitors are actually reading out current translations. Assuming that has been capturing data properly, we just need to log in and review the data.

---

All of this is to say my preference is to remove non-EN translations until we are able to create a plan for if/how we want to support localized documentation and which locals we will support.

[Koooooo-7]

Yea, I agree that the out of date docs maybe a disservice when we do have lots of breaking changes. The reality is, those sites' most part of the basic configuration/usage works . So I don't think we need remove it directly.
On the other side, I don't think the exist contents in search engine from other ref-links sites which doesn't links to non-EN site path should be invalid directly either.
Alternatively, we move to only keep the EN (and CN? @sy-records ) site, we needs some redirect solutions for those non-EN/CN paths directly to the EN contents (they have the same paths and structures).

[andrii-bodnar]

Hi, I just landed here by accident and would like to add some of my thoughts.

I think the main problem with the current setup is that the sources and localization files are in separate repositories. So it is a lot of work for a potential contributor to suggest new translations, especially if the sources are not synchronized with the translations (they have to go to the main repo, take the current source files, compare them to the translations from the separate repo, and then suggest new translations).

The community translators can work together in Crowdin, for example, translations would be delivered as PR, and volunteers can raise issues for problematic strings via Crowdin. In addition, everything could be automated via CI/CD (pushing sources to Crowdin, downloading translations).

You can also check out how Docusaurus manages i18n for their website.

I believe that a localized website can attract more users who are not fluent in English. Providing content in their native language makes the site more accessible and user-friendly, and encourages greater engagement from a diverse audience.

By the way, Crowdin is free for OSS. If you decide to improve the 18n flow and update the translation status, I can help with automated integration with Crowdin.

[sy-records]

I'll update CN's as they are released.

None of the @docsifyjs/translators team members seem to be active anymore.

I think we can try Crowdin.

[Koooooo-7]

Hi @andrii-bodnar , thx for your suggestion.
I have a quick shoot on Crowdin. It seems use something like the fine-tuning AI translator or 3rd translation providers to do the job. (correct me if I do misunderstanding something).
And I don't much clear understand about the sample you mentioned in Docusaurus.

So, before we consider the efforts about moving to Crowdin.

Could you plz provide more info about What we need prepare before we use the Crowdin :

• Do we need have one AI providers key? or order the 3rd translation provider?
• Based on our project current i18n things, what the structures of the i18n changes we may need to do?

[andrii-bodnar]

Hi @Koooooo-7! Currently, Crowdin supports the following AI providers:

• OpenAI
• Google Gemini
• Microsoft Azure OpenAI
• Mistral AI
• Anthropic

So it's possible to use them to pre-translate existing or new content. In addition, community contributors can also suggest their own translations.

And I don't much clear understand about the sample you mentioned in Docusaurus.

This was done to provide an example of how it can be implemented (it is an interesting approach, but more complex to set up).

Do we need have one AI providers key? or order the 3rd translation provider?

You can use your own key. Visit the Crowdin AI article for more details.

Based on our project current i18n things, what the structures of the i18n changes we may need to do?

I'd suggest keeping the source files and translations within the current repository (use some subdirectories for the translated documents).

For example:

.
├── docs/locales
│   ├── en
│   │   └── ...
│   └── es
│   │   └── ...
│   └── de
│   │   └── ...
└── ...