I've built a XLIFF transformer for Docusaurus i18n

[anatolykopyl]

It's called mdx2xliff.

After countless problems with machine translation breaking MDX syntax, I've decided to go with an another approach, than the one described in the docs.
Instead of uploading whole files to Crowdin or any other translation service, I first split the file into two parts:

• XLIFF - an xml with only the strings that are to be translated;
• SKL - a skeleton file that only has the structure of the document, with every string replaced by a placeholder.

This is actually not an uncommon approach. Almost every translation service accepts XLIFF files, including Crowdin.

Now I hand the XLIFF file to whatever service is responsible for i18n (Crowdin for example). After the translation is done, I use my tool to do the reverse operation and reconstruct MDX files from existing skeleton files and translated XLIFFs.

The main benefit of this way of translating is that you never let the translation service touch any code, only the text that needs to be translated.

This has resulted in a completely bug-free translation pipeline. There is a drop in the quality of the translation, but I’d take it over having to fix hundreds of compile breaking errors any day.

For example, a file like this:

# My file

With a paragraph, that contains a [link](https://example.com/)

Will be split into a XLIFF file:

<xliff>
	<trans-unit id=“0”>
		<source>My file</source>
		<target></target>
	</trans-unit>
	<trans-unit id=“1”>
		<source>With a paragraph, that contains a</source>
		<target></target>
	</trans-unit>
	<trans-unit id=“2”>
		<source>link</source>
		<target></target>
	</trans-unit>
</xliff>

(simplified for brevity)

And a SKL file:

# %%%0%%%

%%%1%%%[%%%2%%%](https://example.com/)

We feed the XLIFF into Crowdin and never have to deal with DeepL messing up our URL, for example.

[Josh-Cena]

That looks like a really cool idea! I wonder if it can be supported by the Docusaurus MDX loader.

[anatolykopyl]

Thanks!
I'm sure it's possible, but I don't know why would you do that. Like a way to integrate i18n into the build command?

[Josh-Cena]

Like a way to integrate i18n into the build command?

i18n is already "integrated into the build command"—our build has to figure out where the i18n files live and produce HTML for each of them :) I'm wondering whether our MDX loader can take a source of XLIFF files and MDX backbones and dynamically assemble Markdown on-the-fly during loading, without an intermediate build step.

[anatolykopyl]

Oh, didn't think about it that way! Actually now that I see how it could be all integrated it seems very natural, that this tool could live as a part of the translation workflow.
Seems like it should be very possible, especially since the "reconstruction" of the translated files doesn't require any AST work at all — it's all just a bunch of search and replaces.

[slorber]

That's a pretty cool technique, thanks for sharing it 👍