w:lang (Language)

Specifies the language tag for the run text to control spell-checking and grammar-checking.

Parent elements

w:rPr

Description

w:lang specifies the natural language of the run text, controlling which spell-check and grammar-check dictionaries are used. It is defined in ECMA-376 Part 1 §17.3.2.20.

The value uses IETF BCP 47 language tags (e.g. en-US, de-DE, fr-FR). Three separate attributes cover Latin/Western, East Asian, and complex-script (bidirectional) text segments.

Attributes

Attribute	Type	Possible Values	Description
`w:val`	`ST_Lang`	BCP 47 language tag, e.g. `en-US`, `de-DE`, `fr-FR`, `ja-JP`.	Language for Latin and Western script characters.
`w:eastAsia`	`ST_Lang`	BCP 47 language tag, e.g. `zh-CN`, `ja-JP`, `ko-KR`.	Language for East Asian script characters.
`w:bidi`	`ST_Lang`	BCP 47 language tag, e.g. `ar-SA`, `he-IL`.	Language for complex-script (bidirectional) characters.

Examples

<w:rPr>
  <w:lang w:val="de-DE"/>
</w:rPr>

new RunProperties(
  new Languages { Val = "de-DE" });

<!-- Multilingual: English, Japanese, Arabic -->
<w:rPr>
  <w:lang w:val="en-US" w:eastAsia="ja-JP" w:bidi="ar-SA"/>
</w:rPr>

new RunProperties(
  new Languages 
  { 
    Val = "en-US",        // Western/Latin text
    EastAsia = "ja-JP",   // Japanese text
    Bidi = "ar-SA"        // Arabic text
  });

<!-- Suppress proofing (no spell/grammar check) -->
<w:rPr>
  <w:lang w:val="x-none"/>
</w:rPr>

new RunProperties(
  new Languages { Val = "x-none" });  // Suppress spell-check

Common Language Tags (BCP 47)

Language	Code	Script	Use Case
English (US)	`en-US`	Latin	Most common English variant
English (GB)	`en-GB`	Latin	British English spelling
German	`de-DE`	Latin	German with umlauts
French	`fr-FR`	Latin	French with accents
Spanish	`es-ES`	Latin	Spanish Castilian
Japanese	`ja-JP`	Hiragana/Kanji	Japanese mixed script
Chinese (Simplified)	`zh-CN`	Hanzi	Chinese mainland
Chinese (Traditional)	`zh-TW`	Hanzi	Chinese Taiwan
Korean	`ko-KR`	Hangul	Korean
Arabic	`ar-SA`	Arabic	Arabic Saudi Arabia
Hebrew	`he-IL`	Hebrew	Hebrew Israel
No Linguistic	`zxx`	—	Suppress all proofing
None	`x-none`	—	Suppress proofing

Notes

Omitted Value: If w:lang is missing, the document’s default language (or application default) is used for spell-check.
BCP 47 Standard: Language tags follow IETF BCP 47 format (language-region); region is optional.
Spell-Check Dictionaries: Office downloads/uses language-specific dictionaries based on tag.
Grammar Check: Grammar rules also vary by language; same language tag applies to both.
Script Separation: w:val (Latin), w:eastAsia (CJK), w:bidi (RTL) handle different script blocks independently.
Mixed-Language Runs: Use same w:r with all three attributes for documents with multiple scripts.
Region Variants: en-US vs. en-GB affects spell-check dictionary (e.g., “color” vs. “colour”).
Proofing Suppression: x-none or zxx disables proofing entirely; useful for code, acronyms, proper nouns.
Document-Level Default: Set w:lang on paragraph style or document defaults for consistency.
Accessibility: Screen readers may use language tag to select appropriate pronunciation/voice.
Compatibility: Language tags render consistently across all Office versions; unknown tags default to application language.