Crowdin questions, issues, tips, feedbacks...

[slorber]

Crowdin questions, issues, tips, feedbacks...

As the i18n support is now available in Docusaurus 2

Let's have this issue to discuss anything about Crowdin so that the community can help each other.

Discuss other SaaS translation softwares here

Disclaimer

Docusaurus 2 does not force you to use Crowdin, and you are free to use another SaaS if you want.

Crowdin is not a silver bullet but it gets the job done successfully for some websites like Jest and Docusaurus.

Like any SaaS software, it has its own release lifecycle, bugs, missing features, legacy, weird behaviors.

The Docusaurus team has absolutely 0 control over Crowdin apart from being in touch with their support team and suggesting possible improvements.

[hatton]

Tweaks to the English mess up translations

With default crowdin settings, we get this scenario:

1. A document is translated in Crowdin

2. Someone marks all the strings as “approved”

3. Someone makes a change to the English original, perhaps something as simple as fixing a typo.

4. During the next sync, Crowdin notices that the paragraph changed. It will remember the original translation in its memory, but it will mark the paragraph as untranslated and unapproved.

5. Crowdin download will now give us the English paragraph instead of the translated one.

6. Our site now has a mixed language document until the translator comes along and clicks the right buttons to tell Crowdin that actually, the old translation is still correct.

We think we can solve this by doing two things:

1. Tell Crowdin “If anything in a document is not translated and approved, then do not download it to us at all”. (skip_untranslated_files).

2. Start committing translations into the git repository.

The idea is, once a file is full translated and approved, we have that version in the repo so that we can keep publishing it while we wait for someone to go to Crowdin to either do cleanup or make actual new translations (in case there really is new material).

A significant con of this approach is that absolutely every last thing must be translated and approved, including image links that Crowdin would normally hide from that translator.

Has anyone else faced this problem? How did you solve it?

[slorber]

Has anyone else faced this problem? How did you solve it?

I don't know, I think most users would allow mixed language by default, and try to catch up asap when it's detected.

Start committing translations into the git repository.

Not a bad idea, but keep in mind that you should rather avoid editing those files on Git. Bi-directional sync of edits of Markdown files does not work well in my experience. In general, uploading translated Markdown files from Git to Crowdin is unreliable and Crowdin fails to match translated paragraphs with the original paragraph. It's not an easy problem to solve on their side unfortunately and they acknowledge these limitations. If you commit to Git, I suggest to never edit, and let the Crowdin integration only update from Crowdin to Git, not the opposite.

The idea is, once a file is full translated and approved, we have that version in the repo so that we can keep publishing it while we wait for someone to go to Crowdin to either do cleanup or make actual new translations (in case there really is new material).

So you want to have all translations files in the repo (possibly a bit outdated?), and eventually let Crowdin override some of those by downloading fresh translations with skip_untranslated_files ? That seems like a nice trick to me, worth giving it a try and provide us feedback 👍

---

Note, you may find useful information in the i18n RFC issue: #3317. There are some alternative translation strategies used by other projects that you might like better than Crowdin 🤷‍♂️ for example you could try using one fork per language.

[domeav]

I am a happy docusaurus user, (currently on v2.4.3 and soon-to-be on v3). Our documentation website is written in French, then translated in English and German with a Crowdin+DEEPL combo.
I recently noticed that Crowdin changed the way they handle links. I'll quote their support team after I described my issue:

We recently rolled out some major improvements to the markdown file format and now the links are treated differently than they were before. Before they were considered as tags, but now they appear as plain text. Thus looks like due to these changes your links were translated by DeepL. Unfortunately, I was informed by our Product team that we are not planning to change the logic of how links are treated. Sincerely sorry for the inconvenience!

So, unless the MT engine is markdown-aware (and deepl is not), this behaviour breaks docusaurus websites. Is there something I am missing?

For instance: this string "[page d'accueil](/ma-page(d'accueil)" is translated "home", and this breaks docusaurus i18n workflow as the page name should not be translated.

I can't be the only one using crowdin with MT: how do you deal with this?

[slorber]

Sorry to hear that. I understand how these unplanned changes on an existing workflow that used to work can be annoying. Unfortunately we don't control the behavior of Crowdin, not use MT on our own Docusaurus website so we are not affected by this issue.

The best I could recommend is to find another tool to apply MT that suits your needs, if Crowdin is not willing to revert this behavior change. We can't do anything on our side apart complaining to their support.

[domeav]

If multiple users are complaining to their support, they might be more receptive. I'm hoping others will chime in.
BTW, I've suggested they could convert the markdown strings to html before submitting them to the MT engines - I guess the translation will be more html-aware than markdown-aware. Crowdin told me they would consider this 🤞