Repository navigation
Bug: CrowdIn integration needs to be reconsidered #111
Description
Bug description
Translators got a message today that they had 16,000 new strings to translate -- I got some very angry messages about it! I've deleting the website files from CrowdIn as fast as the interface will let me. Not only is the actual on-CrowdIn layout a bit of a disorganized mess (the site is contained within many many subfolders and layers of subfolders), but every single HTML attribute with quotes around it is being interpreted as a translatable string.
Reacted by marcuspollio
Reacted by kaktus Jacek
Activity
marcuspollio commentedon Oct 22, 2026
Hi @chennes
Thanks for reporting the issue.
Indeed, "dumping" all the website content to CrowdIn is pretty bad, should have though about it beforehand, sorry again!
Some possible solutions to evaluate:
A) Provide a limited subset to translate via CrowdIn
Languages scope:
The FreeCAD CrowdIn currently has a bit more than 70 languages with about half at less than 10% completion. The main target is the FreeCAD software. The website is a "side project" that can potentially use the same platform (if we can make it work properly). The current "homepage" website has about 30 languages mostly complete. Obviously, each added language contributes to increased work, build time, and filesize. Currently, the configuration of the new website has 13 languages configured (see
config/_default/languages.yamlandconfig/_default/module.yaml), with 7 languages enabled for production (config/production/languages.yaml), and 6 more currently disabled. That can of course change in the future seeing how it works or not.So, if we were to try again with CrowdIn and a limited subset of languages, we could do that in the
crowdin.ymlconfig via theexcluded_target_languagesfield, which is not very convenient (a similar "include" option does not exist for some reasons).Or via the settings in the web interface for file target languages. I suppose the source file has to exist before such option is available, but not sure. I don't know if it works for folders as well.
Maybe creating a new CrowdIn project would be easier to manage only website-related translations?
Pages scope:
IMHO, targeting only a subset of pages to be translated (i.e. the most "important" ones) could be OK. Those could be all 36 sections pages (
_index.md), or only the 13 top-level sections plus the homepage. This is open to discuss.Front matter:
I have not seen how the front matter fields are exposed on the CrowdIn interface. In most cases, the field key names do not indicate if they are to be translated or now.
It could be easy to define that only the
title,linkTitle,description,caption, andlabelparams must be translated. But without translators actually reading the website documentation, I can imagine quite some confusion and useless work. If CrowdIn is effectively also used for the new website translations, some communication and on-boarding (in addition to the documentation, as that is often skipped) would be needed.Shortcodes:
The new website makes extensive use of Hugo shortcodes as a way to customize the layout and content when the default markdown syntax falls short. While all currently implemented shortcodes are fairly well documented, I doubt many have actually read any of it.
As expected and illustrated by the screenshot in OP, the CrowdIn markdown parser does not understand the Hugo shortcode syntax, nor does it provide any custom components capabilities.
Like with front matter fields, we could define that only the
titleandlabelattributes in shortcodes have to be translated, the rest left untouched. Not sure how well it would work in practice.Markdown:
Given the screenshot in OP, it looks like standard Markdown elements like images are not supported, meaning that their title and alt/description cannot be translated (i.e.
). I have not seen if other elements like lists, tables, etc. are supported or not.i18n theme strings:
The
i18n/en.yamltranslation tables for the theme strings should work normally, I have not tested though. Currently, there's about 100 table entries, some new entries may be added in the future but I don't think that would double it. This is probably the most straightforward aspect to translate for the website via CrowdIn.B) Adapt the website to use translations from data files or i18n only
One quite involved option would be to refactor and change substantially how the website config and theme work, and rely only on translated data files (e.g.
en.yamlorfr.json) or i18n theme strings. Not sure how feasible and practical that is (Hugo is actually pretty impressive in some obscure way sometimes). The goal would be to set up the translation via CrowdIn in the simplest manner with only words or full sentences to translate, without any context. This would make the workflow quite close to the one currently used for the FreeCAD software UI strings, but would strip what is IMHO quite valuable for a website: the page context. Also in case some of the stack changes (e.g. SSG change, Weblate instead of CrowdIn, etc) this may be the least portable solution.C) Do not rely on CrowdIn for translation and use the CMS instead
The CMS is specifically designed to work with SSGs, and its config is tailored to the website project.
While not 100% perfect, and needing some workflow adaptation, the issues we are facing with CrowdIn do not exist with the CMS (there are some other issues though). The website structure is way more comprehensible, pages can be searched, filtered, sorted, rearranged, media resources are manageable, front matter fields are exposed or hidden as they are intended with proper value types or dialogs, the Markdown parser is way more powerful, custom components for shortcodes are available. In short, it's the CMS job to achieve a good workflow for a SSG website project use case (i.e. CrowdIn is not designed for that in the first place).
So, what is the conclusion?
Personally, I'm OK to try with A) if more people agree to give it a go again. I would very much prefer not to touch any of B).
What do you think?
FYI @kaktusus @FC-FBXL5
kaktusus commentedon Oct 22, 2026
Please work together with the team and make these decisions collectively.
In my opinion, the main issue with the previous import was technical, as it extracted many strings that were not necessarily needed at this stage (unless I missed some prior context). Was there any announcement or discussion about this import in the translators' section on the forum?
I suggest breaking the whole process down into test phases. Let's set up a clearly designated test environment—for instance, we could create a temporary test setup within the FreeCAD-addons project for trial purposes.
You mentioned a lot of technical details that I'm not fully familiar with, which most likely contributed to the issues we encountered. We need to find a way to manage these complex elements or simply exclude them during the initial stage. Producing documentation that no one will read doesn't make sense.
Let's prepare a small test batch first. We should stick with Crowdin for now—if other projects managed to configure it successfully for their needs, we can do it too.
kaktusus commentedon Oct 22, 2026
https://forum.freecad.org/viewtopic.php?t=108106
marcuspollio commentedon Oct 23, 2026
Hi @kaktusus
Thanks for your reply and the message in the forum!
As you rightly pointed out, this CrowdIn "bridge" is still in the testing phase, so any feedback is welcome.
IMHO, moving forward step by step (i.e. test phases), even if that means a large part of the website will not be translated in time for its GA, is acceptable. It may allow to find a suitable workflow and compromise, and adapt accordingly.
I don't know how feasible that is on the CrowdIn side, in particular for admins/managers:
homepage.po.en,zh,es,fr,pt,ar,ja,ru,de,tr,it,pl,nl), then when required, new languages can be added on both sides (i.e. website config and CrowdIn "FreeCAD-website"). When a language reaches a certain threshold, they are enabled and publicly available for the live website.What do you think?
kaktusus commentedon Oct 23, 2026
I'm in favor of it.
I agree with all the points.
Talk to @yorikvanhavre about the possibility of creating a separate project for the website. I expect he might want to be its owner, so it's definitely worth asking him about it.
FC-FBXL5 commentedon Oct 23, 2026
I think an individual Crowdin project for the website is overdue
chennes commentedon Oct 24, 2026
We can absolutely do that: @yorikvanhavre reached out to the folks at CrowdIn a few weeks ago to investigate whether they would be willing to give us an Enterprise account (so the FPA could "own" the projects and then individual humans could be delegated to manage, etc.). I don't think he heard anything back from them. A next-best thing would probably be for us to create a new account, detached from any particular human being, with the FreeCAD infrastructure team having access to it. We could then import the existing projects, and add a new one for the website.
kaktusus commentedon Oct 24, 2026
Ideologically, I agree, but from a technical and practical standpoint, I don't think this is really feasible.
A Crowdin account has to be associated with someone, just like any other account. Actions are attributed to specific users — that's simply how these systems work nowadays.
We could try creating an account under the FPA's name, with collective responsibility, but I don't think that's a particularly healthy practice. If everyone accesses the same account, all their activity will be recorded under the same identity. It would be difficult to determine who did what without additional effort or complications.
Ideally, we should have an organizational account with individual user access and appropriate permissions, rather than a shared account used by multiple people.
I don't know what Crowdin has to offer in this regard.
emmm
https://support.crowdin.com/enterprise/organization/
An Enterprise account solves many of these issues, but it is still tied to a single primary owner.
I agree with the idea of having the FPA own and manage the projects. However, I would avoid creating a shared account for multiple people.
According to Crowdin's documentation, the standard Crowdin platform is user-account-centric: projects are owned by individual users, and project ownership cannot be transferred. Crowdin Enterprise, on the other hand, supports an organization-centric model in which projects and localization resources belong to the organization rather than an individual.
This would allow the FPA to manage the projects centrally while individual team members use their own accounts with appropriate permissions. It would also avoid the accountability issues associated with sharing a single set of credentials.
Crowdin Enterprise also provides a migration path for existing projects, so this seems worth exploring further. The remaining question is whether Crowdin would be willing to provide the FPA with a suitable Enterprise arrangement for an open-source project.
kaktusus commentedon Oct 24, 2026
@marcuspollio
If you need an translator to work on the tests, let me know.
chennes commentedon Oct 24, 2026
I've submitted a request for an Enterprise account for the FPA, which solves many of these organizational problems. Their Open Source page implies that they sometimes grant such a thing, and their immediate response was a request for more information, not an outright "no" 😁 .
kaktusus commentedon Oct 24, 2026
The first step is done,
and I think we've had a little success.
🍻
chennes commentedon Oct 25, 2026
They have granted us the "Team+" Enterprise account I requested, it will be hosted at freecad.crowdin.com once I get things set up. I think we should probably not try to move over to that new setup until after the 26.3 release, for the actual source code strings, but I can set up a project for this website now.
chennes commentedon Oct 25, 2026
Here's a temporary sign-up link for the Website project (there is nothing there yet, I'm just laying the groundwork): https://freecad.crowdin.com/u/signup?hash=ac048440ea26feff369a9053c59271e62
kaktusus commentedon Oct 25, 2026
Can I post this content on the forum ❓
chennes commentedon Oct 25, 2026
As long as it's clear that this is still a Work in Progress :).
marcuspollio commentedon Oct 27, 2026
Hi there!
Thanks a lot @chennes for the enterprise/org request and layout out the groundwork!
That will probably be much easier to manage 😁
Here is a Pull Request to update the CrowdIn config for the website.
This only adds the homepage and the theme strings for now, as discussed above.
There are a few more things to update (repo vars/secrets and parser settings), but then it should be pretty much ready for testing I suppose.
Once these tests are successful and the documentation is updated, an announcement will be made to inform translators that everything is ready and they can get started if they so desire 😉
kaktusus commentedon Oct 27, 2026
Excellent.