docs' export in docx format : corrector in english and not in the language of the document

[Vincentparisgithub]

Bug Report

Before you file your issue
When i export Docs in Docx (and maybe in odt version), then if you open it with Words, the defaut language of the corrector is in english, while my text is on french

Problematic behavior
we need to change the language of the corrector in Words.

Expected behavior/code
we would like that the docx's export, will be automatically in the native language of the document

Steps to Reproduce

[virgile-dev]

@Vincentparisgithub I think it might be your local setup. In word you can chose the language of the corrector.
@StephanMeijer appreciate your insight on this

[Vincentparisgithub]

I am not sure this is the answer,
Yes of course we can change the language in words, but my point was "why the docs converted to docx are in english

Please try one last time : I have word, by default the corrector is in french, and my PC set up in french.
I write a Docs in french, then i export it into a DOCX.
Do now i have a docx files on my PC. I open this docx with word, and the corrector of Word is exceptionnaly by default in english

But if i open a new docx on my pc, then the default language of the corrector of words is coming back to french as usual.
It seems that the docs converted to docx, is setting up something on this Docx that says to Word that this document is in english.

[StephanMeijer]

Thanks @virgile-dev for bringing this to my attention! @AntoLC would love your expertise on this as well.

@Vincentparisgithub you're absolutely right — this is not a local setup issue. The exported DOCX file explicitly sets the document language to English, which causes Word to switch its spellchecker.

Root cause

The DOCX export uses BlockNote's DOCXExporter, which embeds a styles.xml template containing:

<w:lang w:val="en-NL" w:eastAsia="en-GB" w:bidi="ar-SA" />

This w:lang w:val attribute is what Word reads to determine the proofing language. Since it's hardcoded to en-NL, every exported document gets English spellchecking regardless of the actual content language.

BlockNote already supports this

BlockNote added a locale parameter in PR #1937 (addressing issue #1896). The API now accepts:

await exporter.toBlob(blocks, {
  locale: "fr-FR", // BCP 47 / RFC 4646 format
  sectionOptions: {},
  documentOptions: {},
});

See: toBlob() signature · toDocxJsDocument() signature · locale→styles.xml replacement logic

Internally it does a regex replacement on the w:lang w:val attribute in styles.xml with the provided locale, defaulting to en-US if omitted.

What we need to do

In our codebase, the DOCX export in ModalExport.tsx currently does not pass a locale to toBlob(). The fix should pass the user's language (available via i18next.language) to the export call.

One consideration: i18next.language may return short codes like "fr", but the OOXML spec (ECMA-376 §22.9.2.6) expects BCP 47 tags — ideally with region subtag ("fr-FR", "de-DE"). We may need a small mapping.

---

Assisted by Claude Opus 4.6

[StephanMeijer]

w:lang should be omitted when the document language is unknown

When we don't know the document's language, the DOCX export should not define w:lang at all. Defaulting to any language — including en-US — forces that language's spellchecker on the user.

Why this matters

BlockNote currently defaults to en-US when no locale is passed (source). This actively forces English spellchecking — the exact problem reported here.

The language problem

We have a few signals available, but none of them prove the document is in a specific language:

• User's UI language (i18next.language) — a French-speaking user may write a document in English
• System/installation language (e.g. via an environment variable) — the platform may be deployed in French but serve users writing in any language
• The document itself — Docs has no per-document language field, and even if it did, a single document can contain multiple languages

So any language we set on the exported DOCX is a best guess at best. When we can't determine the language, we should not force one.

Why omitting w:lang is the right approach

RFC 3066 §5 is clear:

"You SHOULD NOT use the UND (Undetermined) code unless the protocol in use forces you to give a value for the language tag, even if the language is unknown. Omitting the tag is preferred."

A missing w:lang means "no language override" — Word/LibreOffice will use the user's own default language settings. This is universally understood by every DOCX processor and is the most portable option.

Omitting also avoids interoperability problems that even und causes:

• PHPWord crashes on und — a StackOverflow report documents und causing an InvalidArgumentException in PHPWord, a widely-used DOCX library
• LibreOffice has incomplete und support — there is an open feature request to properly handle the und code
• Word ignores und — Microsoft's MS-OI29500 §22.9.2.6 confirms Word ignores values not in its whitelist, so und happens to work in Word — but only by accident, not by design

What we can do on our side now

BlockNote's styles.xml template always includes the w:lang element, and the replacement logic only substitutes the value — it doesn't support removing the element. Until BlockNote changes this upstream, und is our last resort fallback. We have reported this in TypeCellOS/BlockNote#2649.

Proposed fallback chain

i18next.language available → map to BCP 47 (e.g. "fr" → "fr-FR")
i18next.language unavailable → "und" (last resort until BlockNote supports omitting)

---

Assisted by Claude Opus 4.6

[StephanMeijer]

I'll open a PR in BlockNote that should technically resolve this — the exported DOCX currently defaults to English, and the fix will address that.

That said, setting the correct document language on export is tricky: BlockNote doesn't store language metadata on documents¹, though the DOCX exporter already accepts a locale option. On the Docs side you'd need to decide where that value comes from — a per-document setting, the user's locale, a language picker in the export dialog, or a hardcoded default.

---

Assisted by Claude Opus 4.6

Footnotes

1. The document model is a flat array of blocks with no document-level metadata. Language is a runtime parameter passed to DOCXExporter.toDocxJsDocument({ locale }), defaulting to "en-US". ↩

[StephanMeijer]

This will be fixed upstream in BlockNote: TypeCellOS/BlockNote#2651

The fix omits the <w:lang> element entirely when no locale is passed to the DOCX exporter, instead of defaulting to en-US. Per ECMA-376 §17.3.2.20, omitting the element lets Word/LibreOffice auto-detect language from the document content — so the spellchecker will correctly use the document's actual language once this is merged and released.

---

Assisted by Claude Sonnet 4.6

[StephanMeijer]

The BlockNote PR has been merged.

---

Assisted by Claude Opus 4.6