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 🤞

[slorber]

FYI it's possible to force a specific Crowdin parser version, as I explain here:

• [Bug]: Fix the Jest website deploy jestjs/jest#15947 (comment)
• fix(crowdin): force versioned mdx parser even for .md jestjs/jest#15954

For example, if you want to use a specific MDX parser version:

  - source: /website/docs/**/*.mdx
    translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-docs/current/**/%original_file_name%
    type: mdx_v2_4

The parser version of your files can be retrieved by inspecting the "file type icon" with browser devtools on the Crowdin UI. Not convenient UX, but it works:

As of today, we have migrated the Docusaurus website to use the latest mdx_v2_4 parser version, which works well with our new /* #headingId */ syntax:

# Crowdin regularly update their MDX parser, leading to subtle breakage.
# Freezing the parser to a specific version is helpful to ensure things keep
# working when they upgrade their MDX parser.
# See https://github.com/facebook/docusaurus/pull/11432
#
# Note: you can find the parser version of a Crowdin file using browser DevTools
# and inspecting the MDX file icon, it should have a class ".file_type_mdx_v1_2"
# Find the latest version: manually upload a new .mdx file, then inspect it
#
# How to upgrade the parser version?
# - Rename /docs to /docs_backup on Crowdin UI (same for other mdx folders)
# - Update the parser version of this config file
# - Use the CLI to re-upload the MDX source files: they should now have the new parser version
# - Use the CLI to download the translations
# - Build the full i18n site to ensure it still works (the new parser might break things)
# - Make sure the site content remains translated (normally /docs & /docs_backup share the translation strings)
# - If things work well, you can merge the config update and delete the mdx backup folders on Crowdin UI
mdx_file_type: &mdx_file_type mdx_v2_4

#
# Files configuration
#
files:
  - source: /website/i18n/en/**/*
    translation: /website/i18n/%two_letters_code%/**/%original_file_name%
    languages_mapping: *languages_mapping

  - source: /website/docs/**/*.mdx
    translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-docs/current/**/%original_file_name%
    languages_mapping: *languages_mapping
    type: *mdx_file_type
  - source: /website/docs/**/*
    translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-docs/current/**/%original_file_name%
    languages_mapping: *languages_mapping
    ignore: [/**/*.mdx]

  - source: /website/versioned_docs/**/*.mdx
    translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-docs/**/%original_file_name%
    languages_mapping: *languages_mapping
    type: *mdx_file_type
  - source: /website/versioned_docs/**/*
    translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-docs/**/%original_file_name%
    languages_mapping: *languages_mapping
    ignore: [/**/*.mdx]

  - source: /website/community/**/*
    translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-docs-community/current/**/%original_file_name%
    languages_mapping: *languages_mapping

  - source: /website/blog/**/*
    translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-blog/**/%original_file_name%
    languages_mapping: *languages_mapping

  - source: /website/src/pages/**/*
    translation: /website/i18n/%two_letters_code%/docusaurus-plugin-content-pages/**/%original_file_name%
    ignore: [/**/*.js, /**/*.jsx, /**/*.ts, /**/*.tsx, /**/*.css]
    languages_mapping: *languages_mapping

The parser version gets set the first time you upload a given file to Crowdin. After that, it stays the same.

To upgrade the parser version (or transition type from md to mdx), what worked for us is to rename /docs to /docs_backup, and then re-upload new source files for /docs so that they get updated to the new parser.

If your Crowdin site "shares duplicate strings" (configurable), normally, most of your translations will be preserved on your newly uploaded source files, and you'll later be able to delete the /docs_backup folder.

I can't guarantee this strategy will work for your site, so make sure to do various backups on Crowdin before running such a process (download a translation archive, translation memory, etc.) in case you lose translations.