DOC-3355: New content_language option to set the lang attribute on the editor content element (#4092)

kemister85 · web-flow · commit bdc1a2aa8c44 · 2026-04-28T22:30:09.000+10:00
* DOC-3355: New content_language option to set the lang attribute on the editor content element * Add deprecation note to spellchecker_language option The TINY-11214 DoD required noting the deprecation on the spellchecker_language config page itself, pointing integrators to content_language as the replacement.
diff --git a/modules/ROOT/pages/8.5.0-release-notes.adoc b/modules/ROOT/pages/8.5.0-release-notes.adoc
@@ -41,6 +41,21 @@ The {productname} {release-version} release includes an accompanying release of
 
 For information on the **<Premium plugin name 1>** plugin, see: xref:<plugincode>.adoc[<Premium plugin name 1>].
 
+=== Spell Checker
+
+The {productname} {release-version} release includes an accompanying release of the **Spell Checker** premium plugin.
+
+**Spell Checker** includes the following change.
+
+==== The Spell Checker plugin now uses the `content_language` option as the default language, falling back to `spellchecker_language` if not set
+// #TINY-11214
+
+Previously, the Spell Checker plugin relied exclusively on the `spellchecker_language` option to determine its default proofing language. There was no way to align the spellchecker language with the content language set on the editor.
+
+In {productname} {release-version}, the Spell Checker plugin now reads the new `content_language` option first and uses its value as the default proofing language. If `content_language` is not set, the plugin falls back to `spellchecker_language`. The `spellchecker_language` option will be deprecated in a future major version; integrators are encouraged to use `content_language` instead.
+
+For information on the **Spell Checker** plugin, see: xref:introduction-to-tiny-spellchecker.adoc[Spell Checker].
+
 === Accessibility Checker
 
 The {productname} {release-version} release includes an accompanying release of the **Accessibility Checker** premium plugin.
@@ -361,6 +376,13 @@ For information on using Enhanced Skins & Icon Packs, see: xref:enhanced-skins-a
 
 // CCFR here.
 
+=== New `content_language` option to set the `lang` attribute on the iframe's `html` element or the inline editor's target element
+// #TINY-11214
+
+Previously, {productname} had no option to set the default content language of the editor. In classic (iframe) mode, the `html` element inside the editor iframe had no `lang` attribute, which failed to meet accessibility standards such as link:https://www.w3.org/WAI/standards-guidelines/act/rules/b5c3f8/[WCAG Success Criterion 3.1.1]. Screen readers and other assistive technologies could not determine the language of the editor content.
+
+In {productname} {release-version}, the new xref:content-localization.adoc#content_language[`+content_language+`] option sets a `lang` attribute on the `html` element of the editor's iframe in classic mode, or on the target element in inline mode. This is separate from the xref:ui-localization.adoc#language[`+language+`] option, which controls the UI language. The Spell Checker plugin also now defaults to `+content_language+` when set, before falling back to `+spellchecker_language+`.
+
 
 [[changes]]
 == Changes
diff --git a/modules/ROOT/pages/content-localization.adoc b/modules/ROOT/pages/content-localization.adoc
@@ -3,6 +3,10 @@
 :description_short: Localize TinyMCE for your language, including directionality.
 :description: These settings configure TinyMCE's language capabilities, including right-to-left support.
 
+== Setting the default content language
+
+include::partial$configuration/content_language.adoc[leveloffset=+1]
+
 == Setting the language on content
 
 include::partial$configuration/content_langs.adoc[leveloffset=+1]
diff --git a/modules/ROOT/partials/configuration/content_language.adoc b/modules/ROOT/partials/configuration/content_language.adoc
@@ -0,0 +1,24 @@
+[[content_language]]
+== `content_language`
+
+The `+content_language+` option sets the default content language of the editor by applying a `+lang+` attribute to the document element. In classic (iframe) mode, the attribute is set on the `+<html>+` element inside the editor's iframe. In inline mode, the attribute is set on the target element specified in the editor's `+selector+` option.
+
+Setting this option helps meet accessibility standards such as link:https://www.w3.org/WAI/standards-guidelines/act/rules/b5c3f8/[WCAG Success Criterion 3.1.1 (Language of Page)], which requires that the default human language of a web page can be programmatically determined.
+
+NOTE: This option is separate from the xref:ui-localization.adoc#language[`+language+`] option, which controls the language of the {productname} user interface. The `+content_language+` option controls only the language attribute of the editor content area.
+
+When the xref:introduction-to-tiny-spellchecker.adoc[Spell Checker] plugin is active, it uses `+content_language+` as its default proofing language. If `+content_language+` is not set, the Spell Checker falls back to xref:introduction-to-tiny-spellchecker.adoc#spellchecker_language[`+spellchecker_language+`].
+
+*Type:* `+String+`
+
+*Default value:* Not set (`+undefined+`)
+
+=== Example: using `content_language`
+
+[source,js]
+----
+tinymce.init({
+  selector: 'textarea',  // change this value according to your HTML
+  content_language: 'fr'
+});
+----
diff --git a/modules/ROOT/partials/configuration/spellchecker_language.adoc b/modules/ROOT/partials/configuration/spellchecker_language.adoc
@@ -1,6 +1,8 @@
 [[spellchecker_language]]
 == `+spellchecker_language+`
 
+IMPORTANT: This option has been marked as *deprecated* as of {productname} 8.5. It will be removed in a future major release. Use xref:content-localization.adoc#content_language[`+content_language+`] instead, which sets both the default content language and the Spell Checker proofing language.
+
 This option specifies the default language used by Spell Checker.
 
 *Type:* `+String+`
