Mar 22, 2025 · May 7, 2025
diff --git a/doc/users/next_whats_new/text_language.rst b/doc/users/next_whats_new/text_language.rst
 Specifying text language
 ------------------------

 OpenType fonts may support language systems which can be used to select different
 typographic conventions, e.g., localized variants of letters that share a single Unicode
 code point, or different default font features. The text API now supports setting a
 language to be used and may be set/get with:

 - `matplotlib.text.Text.set_language` / `matplotlib.text.Text.get_language`
 - Any API that creates a `.Text` object by passing the *language* argument (e.g.,
  ``plt.xlabel(..., language=...)``)

 The language of the text must be in a format accepted by libraqm, namely `a BCP47
 language code <https://www.w3.org/International/articles/language-tags/>`_. If None or
 unset, then no particular language will be implied, and default font settings will be
 used.

 For example, the default font ``DejaVu Sans`` supports language-specific glyphs in the
 Serbian and Macedonian languages in the Cyrillic alphabet, or the Sámi family of
 languages in the Latin alphabet.

 .. plot::
    :include-source:

    fig = plt.figure(figsize=(7, 3))

    char = '\U00000431'
    fig.text(0.5, 0.8, f'\\U{ord(char):08x}', fontsize=40, horizontalalignment='center')
    fig.text(0, 0.6, f'Serbian: {char}', fontsize=40, language='sr')
    fig.text(1, 0.6, f'Russian: {char}', fontsize=40, language='ru',
             horizontalalignment='right')

    char = '\U0000014a'
    fig.text(0.5, 0.3, f'\\U{ord(char):08x}', fontsize=40, horizontalalignment='center')
    fig.text(0, 0.1, f'English: {char}', fontsize=40, language='en')
    fig.text(1, 0.1, f'Inari Sámi: {char}', fontsize=40, language='smn',
             horizontalalignment='right')
diff --git a/lib/matplotlib/_text_helpers.py b/lib/matplotlib/_text_helpers.py
            f"Matplotlib currently does not support {block} natively.")


 def layout(string, font, *, kern_mode=Kerning.DEFAULT):
 def layout(string, font, *,language=None,kern_mode=Kerning.DEFAULT):
    """
    Render *string* with *font*.

        The string to be rendered.
    font : FT2Font
        The font.
    language : str or list of tuples of (str, int, int), optional
        The language of the text in a format accepted by libraqm, namely `a BCP47
        language code <https://www.w3.org/International/articles/language-tags/>`_.
    kern_mode : Kerning
        A FreeType kerning mode.

    """
    x = 0
    prev_glyph_idx = None
    char_to_font = font._get_fontmap(string)
    char_to_font = font._get_fontmap(string)  # TODO: Pass in language.
    base_font = font
    for char in string:
        # This has done the fallback logic
diff --git a/lib/matplotlib/backends/backend_agg.py b/lib/matplotlib/backends/backend_agg.py
        font = self._prepare_font(prop)
        # We pass '0' for angle here, since it will be rotated (in raster
        # space) in the following call to draw_text_image).
        font.set_text(s, 0, flags=get_hinting_flag())
        font.set_text(s, 0, flags=get_hinting_flag(),
                      language=mtext.get_language() if mtext is not None else None)
        font.draw_glyphs_to_bitmap(
            antialiased=gc.get_antialiased())
        d = font.get_descent() / 64.0
diff --git a/lib/matplotlib/backends/backend_pdf.py b/lib/matplotlib/backends/backend_pdf.py
            return self.draw_mathtext(gc, x, y, s, prop, angle)

        fontsize = prop.get_size_in_points()
        language = mtext.get_language() if mtext is not None else None

        if mpl.rcParams['pdf.use14corefonts']:
            font = self._get_font_afm(prop)
            fonttype = mpl.rcParams['pdf.fonttype']

        if gc.get_url() is not None:
            font.set_text(s)
            font.set_text(s, language=language)
            width, height = font.get_width_height()
            self.file._annotations[-1][1].append(_get_link_annotation(
                gc, x, y, width / 64, height / 64, angle))
            multibyte_glyphs = []
            prev_was_multibyte = True
            prev_font = font
            for item in _text_helpers.layout(s, font, kern_mode=Kerning.UNFITTED):
            for item in _text_helpers.layout(s, font, language=language,
                                             kern_mode=Kerning.UNFITTED):
                if _font_supports_glyph(fonttype, ord(item.char)):
                    if prev_was_multibyte or item.ft_object != prev_font:
                        singlebyte_chunks.append((item.ft_object, item.x, []))
diff --git a/lib/matplotlib/backends/backend_ps.py b/lib/matplotlib/backends/backend_ps.py
                thisx += width * scale

        else:
            language = mtext.get_language() if mtext is not None else None
            font = self._get_font_ttf(prop)
            self._character_tracker.track(font, s)
            for item in _text_helpers.layout(s, font):
            for item in _text_helpers.layout(s, font, language=language):
                ps_name = (item.ft_object.postscript_name
                           .encode("ascii", "replace").decode("ascii"))
                glyph_name = item.ft_object.get_glyph_name(item.glyph_idx)
diff --git a/lib/matplotlib/ft2font.pyi b/lib/matplotlib/ft2font.pyi
    def set_charmap(self, i: int) -> None: ...
    def set_size(self, ptsize: float, dpi: float) -> None: ...
    def set_text(
        self, string: str, angle: float = ..., flags: LoadFlags = ...
        self,
        string: str,
        angle: float = ...,
        flags: LoadFlags = ...,
        *,
        language: str | list[tuple[str, int, int]] | None = ...,
    ) -> NDArray[np.float64]: ...
    @property
    def ascender(self) -> int: ...
diff --git a/lib/matplotlib/mpl-data/matplotlibrc b/lib/matplotlib/mpl-data/matplotlibrc
 ## for more information on text properties
 #text.color: black

 ## The language of the text in a format accepted by libraqm, namely `a BCP47 language
 ## code <https://www.w3.org/International/articles/language-tags/>`_. If None, then no
 ## particular language will be implied, and default font settings will be used.
 #text.language: None

 ## FreeType hinting flag ("foo" corresponds to FT_LOAD_FOO); may be one of the
 ## following (Proprietary Matplotlib-specific synonyms are given in parentheses,
 ## but their use is discouraged):
diff --git a/lib/matplotlib/rcsetup.py b/lib/matplotlib/rcsetup.py
    "text.kerning_factor": validate_int,
    "text.antialiased":    validate_bool,
    "text.parse_math":     validate_bool,
    "text.language":       validate_string_or_None,

    "mathtext.cal":            validate_font_properties,
    "mathtext.rm":             validate_font_properties,
diff --git a/lib/matplotlib/tests/test_ft2font.py b/lib/matplotlib/tests/test_ft2font.py
    assert font.get_bitmap_offset() == (6, 0)


 def test_ft2font_language_invalid():
    file = fm.findfont('DejaVu Sans')
    font = ft2font.FT2Font(file, hinting_factor=1, _kerning_factor=0)
    with pytest.raises(TypeError):
        font.set_text('foo', language=[1, 2, 3])
    with pytest.raises(TypeError):
        font.set_text('foo', language=[(1, 2)])
    with pytest.raises(TypeError):
        font.set_text('foo', language=[('en', 'foo', 2)])
    with pytest.raises(TypeError):
        font.set_text('foo', language=[('en', 1, 'foo')])


 def test_ft2font_language():
    file = fm.findfont('DejaVu Sans')
    font = ft2font.FT2Font(file, hinting_factor=1, _kerning_factor=0)
    font.set_text('foo')
    font.set_text('foo', language='en')
    font.set_text('foo', language=[('en', 1, 2)])


 def test_ft2font_loading():
    file = fm.findfont('DejaVu Sans')
    font = ft2font.FT2Font(file, hinting_factor=1, _kerning_factor=0)
diff --git a/lib/matplotlib/tests/test_text.py b/lib/matplotlib/tests/test_text.py
        tick.set_rotation(angle)

    plt.subplots_adjust(left=0.4, right=0.6, top=.99, bottom=.01)


 def test_text_language_invalid():
    with pytest.raises(TypeError, match='must be list of tuple'):
        Text(0, 0, 'foo', language=[1, 2, 3])
    with pytest.raises(TypeError, match='must be list of tuple'):
        Text(0, 0, 'foo', language=[(1, 2)])
    with pytest.raises(TypeError, match='start location must be int'):
        Text(0, 0, 'foo', language=[('en', 'foo', 2)])
    with pytest.raises(TypeError, match='end location must be int'):
        Text(0, 0, 'foo', language=[('en', 1, 'foo')])


 def test_text_language():
    Text(0, 0, 'foo', language='en')
    Text(0, 0, 'foo', language=[('en', 1, 2)])
diff --git a/lib/matplotlib/text.py b/lib/matplotlib/text.py
        super().__init__()
        self._x, self._y = x, y
        self._text = ''
        self._language = None
        self._reset_visual_defaults(
            text=text,
            color=color,
            return 'baseline' if anchor_at_left else 'top'
        return 'top' if anchor_at_left else 'baseline'

    def get_language(self):
        """Return the language this Text is in."""
        return self._language

    def set_language(self, language):
        """
        Set the language of the text.

        Parameters
        ----------
        language : str or list[tuple[str, int, int]] or None
            The language of the text in a format accepted by libraqm, namely `a BCP47
            language code <https://www.w3.org/International/articles/language-tags/>`_.

            If None, then defaults to :rc:`text.language`.
        """
        _api.check_isinstance((list, str, None), language=language)
        language = mpl._val_or_rc(language, 'text.language')

        if isinstance(language, list):
            for val in language:
                if not isinstance(val, tuple) or len(val) != 3:
                    raise TypeError('language must be list of tuple, not {language!r}')
                sublang, start, end = val
                if not isinstance(sublang, str):
                    raise TypeError(
                        'sub-language specification must be str, not {sublang!r}')
                if not isinstance(start, int):
                    raise TypeError('start location must be int, not {start!r}')
                if not isinstance(end, int):
                    raise TypeError('end location must be int, not {end!r}')

        self._language = language
        self.stale = True


 class OffsetFrom:
    """Callable helper class for working with `Annotation`."""
diff --git a/lib/matplotlib/text.pyi b/lib/matplotlib/text.pyi
    def set_antialiased(self, antialiased: bool) -> None: ...
    def _ha_for_angle(self, angle: Any) -> Literal['center', 'right', 'left'] | None: ...
    def _va_for_angle(self, angle: Any) -> Literal['center', 'top', 'baseline'] | None: ...
    def get_language(self) -> str | list[tuple[str, int, int]] | None: ...
    def set_language(self, language: str | list[tuple[str, int, int]] | None) -> None: ...

 class OffsetFrom:
    def __init__(
diff --git a/lib/matplotlib/textpath.py b/lib/matplotlib/textpath.py
        d /= 64.0
        return w * scale, h * scale, d * scale

    def get_text_path(self, prop, s, ismath=False):
    def get_text_path(self, prop, s, ismath=False, *, language=None):
        """
        Convert text *s* to path (a tuple of vertices and codes for
        matplotlib.path.Path).
            The text to be converted.
        ismath : {False, True, "TeX"}
            If True, use mathtext parser.  If "TeX", use tex for rendering.
        language : str or list of tuples of (str, int, int), optional
            The language of the text in a format accepted by libraqm, namely `a BCP47
            language code <https://www.w3.org/International/articles/language-tags/>`_.

        Returns
        -------
            glyph_info, glyph_map, rects = self.get_glyphs_tex(prop, s)
        elif not ismath:
            font = self._get_font(prop)
            glyph_info, glyph_map, rects = self.get_glyphs_with_font(font, s)
            glyph_info, glyph_map, rects = self.get_glyphs_with_font(font, s,
                                                                     language=language)
        else:
            glyph_info, glyph_map, rects = self.get_glyphs_mathtext(prop, s)

        return verts, codes

    def get_glyphs_with_font(self, font, s, glyph_map=None,
                             return_new_glyphs_only=False):
                             return_new_glyphs_only=False, *, language=None):
        """
        Convert string *s* to vertices and codes using the provided ttf font.
        """

        xpositions = []
        glyph_ids = []
        for item in _text_helpers.layout(s, font):
        for item in _text_helpers.layout(s, font, language=language):
            char_id = self._get_char_id(item.ft_object, ord(item.char))
            glyph_ids.append(char_id)
            xpositions.append(item.x)
diff --git a/lib/matplotlib/textpath.pyi b/lib/matplotlib/textpath.pyi
        self, s: str, prop: FontProperties, ismath: bool | Literal["TeX"]
    ) -> tuple[float, float, float]: ...
    def get_text_path(
        self, prop: FontProperties, s: str, ismath: bool | Literal["TeX"] = ...
        self, prop: FontProperties, s: str, ismath: bool | Literal["TeX"] = ..., *,
        language: str | list[tuple[str, int, int]] | None = ...,
    ) -> list[np.ndarray]: ...
    def get_glyphs_with_font(
        self,
        font: FT2Font,
        s: str,
        glyph_map: dict[str, tuple[np.ndarray, np.ndarray]] | None = ...,
        return_new_glyphs_only: bool = ...,
        *,
        language: str | list[tuple[str, int, int]] | None = ...,
    ) -> tuple[
        list[tuple[str, float, float, float]],
        dict[str, tuple[np.ndarray, np.ndarray]],
diff --git a/src/ft2font.cpp b/src/ft2font.cpp
 }

 void FT2Font::set_text(
    std::u32string_view text, double angle, FT_Int32 flags, std::vector<double> &xys)
    std::u32string_view text, double angle, FT_Int32 flags, LanguageType languages,
    std::vector<double> &xys)
 {
    FT_Matrix matrix; /* transformation matrix */

diff --git a/src/ft2font.h b/src/ft2font.h
 #ifndef MPL_FT2FONT_H
 #define MPL_FT2FONT_H

 #include <optional>
 #include <set>
 #include <string>
 #include <string_view>
    typedef void (*WarnFunc)(FT_ULong charcode, std::set<FT_String*> family_names);

  public:
    using LanguageRange = std::tuple<std::string, int, int>;
    using LanguageType = std::optional<std::vector<LanguageRange>>;

    FT2Font(FT_Open_Args &open_args, long hinting_factor,
            std::vector<FT2Font *> &fallback_list,
            WarnFunc warn, bool warn_if_used);
    void set_charmap(int i);
    void select_charmap(unsigned long i);
    void set_text(std::u32string_view codepoints, double angle, FT_Int32 flags,
                  std::vector<double> &xys);
 LanguageType languages,std::vector<double> &xys);
    int get_kerning(FT_UInt left, FT_UInt right, FT_Kerning_Mode mode, bool fallback);
    int get_kerning(FT_UInt left, FT_UInt right, FT_Kerning_Mode mode, FT_Vector &delta);
    void set_kerning_factor(int factor);
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,37 @@
		Specifying text language
		------------------------

		OpenType fonts may support language systems which can be used to select different
		typographic conventions, e.g., localized variants of letters that share a single Unicode
		code point, or different default font features. The text API now supports setting a
		language to be used and may be set/get with:

		- `matplotlib.text.Text.set_language` / `matplotlib.text.Text.get_language`
		- Any API that creates a `.Text` object by passing the language argument (e.g.,
		``plt.xlabel(..., language=...)``)

		The language of the text must be in a format accepted by libraqm, namely `a BCP47
		language code <https://www.w3.org/International/articles/language-tags/>`_. If None or
		unset, then no particular language will be implied, and default font settings will be
		used.

		For example, the default font ``DejaVu Sans`` supports language-specific glyphs in the
		Serbian and Macedonian languages in the Cyrillic alphabet, or the Sámi family of
		languages in the Latin alphabet.

		.. plot::
		:include-source:

		fig = plt.figure(figsize=(7, 3))

		char = '\U00000431'
		fig.text(0.5, 0.8, f'\\U{ord(char):08x}', fontsize=40, horizontalalignment='center')
		fig.text(0, 0.6, f'Serbian: {char}', fontsize=40, language='sr')
		fig.text(1, 0.6, f'Russian: {char}', fontsize=40, language='ru',
		horizontalalignment='right')

		char = '\U0000014a'
		fig.text(0.5, 0.3, f'\\U{ord(char):08x}', fontsize=40, horizontalalignment='center')
		fig.text(0, 0.1, f'English: {char}', fontsize=40, language='en')
		fig.text(1, 0.1, f'Inari Sámi: {char}', fontsize=40, language='smn',
		horizontalalignment='right')
Original file line number	Diff line number	Diff line change
Expand Up		@@ -43,7 +43,7 @@ def warn_on_missing_glyph(codepoint, fontnames):
		f"Matplotlib currently does not support {block} natively.")


		def layout(string, font, *, kern_mode=Kerning.DEFAULT):
		def layout(string, font, *,language=None,kern_mode=Kerning.DEFAULT):
		"""
		Render string with font.

Expand All		@@ -56,6 +56,9 @@ def layout(string, font, *, kern_mode=Kerning.DEFAULT):
		The string to be rendered.
		font : FT2Font
		The font.
		language : str or list of tuples of (str, int, int), optional
		The language of the text in a format accepted by libraqm, namely `a BCP47
		language code <https://www.w3.org/International/articles/language-tags/>`_.
		kern_mode : Kerning
		A FreeType kerning mode.

Expand All		@@ -65,7 +68,7 @@ def layout(string, font, *, kern_mode=Kerning.DEFAULT):
		"""
		x = 0
		prev_glyph_idx = None
		char_to_font = font._get_fontmap(string)
		char_to_font = font._get_fontmap(string) # TODO: Pass in language.
Copy link MemberAuthor QuLogicMay 7, 2025 Choose a reason for hiding this comment The reason will be displayed to describe this comment to others.Learn more. Note, this function is getting rewritten with libraqm, so this is just a note for later.
		base_font = font
		for char in string:
		# This has done the fallback logic
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -189,7 +189,8 @@ def draw_text(self, gc, x, y, s, prop, angle, ismath=False, mtext=None):
		font = self._prepare_font(prop)
		# We pass '0' for angle here, since it will be rotated (in raster
		# space) in the following call to draw_text_image).
		font.set_text(s, 0, flags=get_hinting_flag())
		font.set_text(s, 0, flags=get_hinting_flag(),
		language=mtext.get_language() if mtext is not None else None)
		font.draw_glyphs_to_bitmap(
		antialiased=gc.get_antialiased())
		d = font.get_descent() / 64.0
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -2338,6 +2338,7 @@ def draw_text(self, gc, x, y, s, prop, angle, ismath=False, mtext=None):
		return self.draw_mathtext(gc, x, y, s, prop, angle)

		fontsize = prop.get_size_in_points()
		language = mtext.get_language() if mtext is not None else None

		if mpl.rcParams['pdf.use14corefonts']:
		font = self._get_font_afm(prop)
Expand All		@@ -2348,7 +2349,7 @@ def draw_text(self, gc, x, y, s, prop, angle, ismath=False, mtext=None):
		fonttype = mpl.rcParams['pdf.fonttype']

		if gc.get_url() is not None:
		font.set_text(s)
		font.set_text(s, language=language)
		width, height = font.get_width_height()
		self.file._annotations[-1][1].append(_get_link_annotation(
		gc, x, y, width / 64, height / 64, angle))
Expand DownExpand Up		@@ -2382,7 +2383,8 @@ def draw_text(self, gc, x, y, s, prop, angle, ismath=False, mtext=None):
		multibyte_glyphs = []
		prev_was_multibyte = True
		prev_font = font
		for item in _text_helpers.layout(s, font, kern_mode=Kerning.UNFITTED):
		for item in _text_helpers.layout(s, font, language=language,
		kern_mode=Kerning.UNFITTED):
		if _font_supports_glyph(fonttype, ord(item.char)):
		if prev_was_multibyte or item.ft_object != prev_font:
		singlebyte_chunks.append((item.ft_object, item.x, []))
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -795,9 +795,10 @@ def draw_text(self, gc, x, y, s, prop, angle, ismath=False, mtext=None):
		thisx += width * scale

		else:
		language = mtext.get_language() if mtext is not None else None
		font = self._get_font_ttf(prop)
		self._character_tracker.track(font, s)
		for item in _text_helpers.layout(s, font):
		for item in _text_helpers.layout(s, font, language=language):
		ps_name = (item.ft_object.postscript_name
		.encode("ascii", "replace").decode("ascii"))
		glyph_name = item.ft_object.get_glyph_name(item.glyph_idx)
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -236,7 +236,12 @@ class FT2Font(Buffer):
		def set_charmap(self, i: int) -> None: ...
		def set_size(self, ptsize: float, dpi: float) -> None: ...
		def set_text(
		self, string: str, angle: float = ..., flags: LoadFlags = ...
		self,
		string: str,
		angle: float = ...,
		flags: LoadFlags = ...,
		*,
		language: str \| list[tuple[str, int, int]] \| None = ...,
		) -> NDArray[np.float64]: ...
		@property
		def ascender(self) -> int: ...
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -292,6 +292,11 @@
		## for more information on text properties
		#text.color: black

		## The language of the text in a format accepted by libraqm, namely `a BCP47 language
		## code <https://www.w3.org/International/articles/language-tags/>`_. If None, then no
		## particular language will be implied, and default font settings will be used.
		#text.language: None

		## FreeType hinting flag ("foo" corresponds to FT_LOAD_FOO); may be one of the
		## following (Proprietary Matplotlib-specific synonyms are given in parentheses,
		## but their use is discouraged):
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -1058,6 +1058,7 @@ def _convert_validator_spec(key, conv):
		"text.kerning_factor": validate_int,
		"text.antialiased": validate_bool,
		"text.parse_math": validate_bool,
		"text.language": validate_string_or_None,

		"mathtext.cal": validate_font_properties,
		"mathtext.rm": validate_font_properties,
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -774,6 +774,27 @@ def test_ft2font_set_text():
		assert font.get_bitmap_offset() == (6, 0)


		def test_ft2font_language_invalid():
		file = fm.findfont('DejaVu Sans')
		font = ft2font.FT2Font(file, hinting_factor=1, _kerning_factor=0)
		with pytest.raises(TypeError):
		font.set_text('foo', language=[1, 2, 3])
		with pytest.raises(TypeError):
		font.set_text('foo', language=[(1, 2)])
		with pytest.raises(TypeError):
		font.set_text('foo', language=[('en', 'foo', 2)])
		with pytest.raises(TypeError):
		font.set_text('foo', language=[('en', 1, 'foo')])


		def test_ft2font_language():
		file = fm.findfont('DejaVu Sans')
		font = ft2font.FT2Font(file, hinting_factor=1, _kerning_factor=0)
		font.set_text('foo')
		font.set_text('foo', language='en')
		font.set_text('foo', language=[('en', 1, 2)])


		def test_ft2font_loading():
		file = fm.findfont('DejaVu Sans')
		font = ft2font.FT2Font(file, hinting_factor=1, _kerning_factor=0)
Expand Down
Original file line number	Diff line number	Diff line change
Expand Up		@@ -1190,3 +1190,19 @@ def test_ytick_rotation_mode():
		tick.set_rotation(angle)

		plt.subplots_adjust(left=0.4, right=0.6, top=.99, bottom=.01)


		def test_text_language_invalid():
		with pytest.raises(TypeError, match='must be list of tuple'):
		Text(0, 0, 'foo', language=[1, 2, 3])
		with pytest.raises(TypeError, match='must be list of tuple'):
		Text(0, 0, 'foo', language=[(1, 2)])
		with pytest.raises(TypeError, match='start location must be int'):
		Text(0, 0, 'foo', language=[('en', 'foo', 2)])
		with pytest.raises(TypeError, match='end location must be int'):
		Text(0, 0, 'foo', language=[('en', 1, 'foo')])


		def test_text_language():
		Text(0, 0, 'foo', language='en')
		Text(0, 0, 'foo', language=[('en', 1, 2)])