Along with#29695, thislanguage parameter is an additional setting that may affect text layout. As with the other PR, this is not complete, but rather something to get the API decided upon (and likely will be rebased on raqm PR after it's done.)

There are two parts to the API:

thelanguage parameter attached toText, and any other API that wraps it (i.e.,Axes.text orAxes.annotate)
thelanguage parameter in backend'sRenderer.draw_text

At the moment, for both, I have set these tostr | list[tuple[str, int, int]] where the latter denotes a list of (language, start, end)-tuples. However, this was before I found out aboutthe font feature machinery, and it is possible that we may wish to use that syntax instead, at least for API part 1. For part 2, it's a little nicer to have the explicit types, just for passing to the FT2Font extension, but this may not be relevant to other implementations.

PR checklist

[n/a] "closes #0000" is in the body of the PR description tolink the related issue
new and changed code istested
Plotting related features are demonstrated in anexample
New Features andAPI Changes are noted with adirective and release note
Documentation complies withgeneral anddocstring guidelines

QuLogic added the topic: text label

Mar 22, 2025

QuLogic added this to thev3.11.0 milestone

Mar 22, 2025

github-actionsbot added backend: pgf backend: agg backend: ps backend: pdf backend: svg backend: cairo topic: text/fonts topic: canvas and figure manager labels

Mar 22, 2025

QuLogic force-pushed thetext-language branch fromffd43e9 tob3cfa4dCompare

March 22, 2025 09:35

Copy link

Contributor

anntzer commentedMar 22, 2025•
edited
Loading

re: adding language to draw_text: the general discussion about extensibility of renderer API applies, i.e.

if you're going to add language as a parameter to draw_text then it should be at least keyword-only.
it's likely that the more maintainable API would likely to just embed language as part of fontproperties (it's not really different from e.g. font features, I'd think) and tell the backend to read that info.
for draw_text we have actually more or less given up on having a "clean" renderer API because we pass the whole Text instance to draw_text (perPropagate mpl.text.Text instances to the backends and fix documentation #1081) anyways so perhaps backends that care could also just read that info off the Text instance. It feels a bit dirty, but heh... ("dirty" because we as well may just have a renderer API that'srenderer.draw_text(textobj) to start with...)

anntzer mentioned this pull request

Mar 22, 2025

Add font feature API to Text#29695

Merged

5 tasks

Copy link

Contributor

anntzer commentedMar 28, 2025

Side point regarding allowinglist[tuple[str, int, int]] as language setting: this may be a problem if one usessomelanguage[idx:] to set the language from an index up to the end of the string (whose length could technically be modified later, even though it's not clear this necessarily makes much practical sense). Likely you needlist[tuple[str, int, int | None]] (and then you may possibly support None (=0) for the start as well).

QuLogic mentioned this pull request

Apr 16, 2025

Fix signature of disabled draw methods#29923

Merged

1 task

Copy link

MemberAuthor

QuLogic commentedApr 16, 2025

In the call a couple weeks ago, we decided to drop the newlanguage parameter todraw_text, because that already had amtext parameter which contained the wholeText object. This would avoid any signature introspection.

However, one followup is thatRenderer.get_text_width_height_descent wouldalso depend on font features/language settings, and really should get these passed through somehow as well.

QuLogic force-pushed thetext-language branch fromb3cfa4d to161e393Compare

April 17, 2025 08:40

github-actionsbot removed backend: pgf backend: svg backend: cairo topic: canvas and figure manager labels

Apr 17, 2025

QuLogic force-pushed thetext-language branch from161e393 tof240057Compare

April 17, 2025 08:45

QuLogic mentioned this pull request

May 2, 2025

Implement text shaping with libraqm#30000

Merged

5 tasks

QuLogic commented

May 7, 2025

View reviewed changes

lib/matplotlib/_text_helpers.pyShow resolvedHide resolved

QuLogic force-pushed thetext-language branch fromf240057 to736bb64Compare

May 7, 2025 06:29

anntzer reviewed

May 10, 2025

View reviewed changes

lib/matplotlib/_text_helpers.py Outdated



		deflayout(string,font,*,kern_mode=Kerning.DEFAULT):
		deflayout(string,font,language,*,kern_mode=Kerning.DEFAULT):

Copy link

Contributor

anntzerMay 10, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

These params should be kwonly? (throughout most of the PR, I think)

anntzer reviewed

May 10, 2025

View reviewed changes

src/ft2font_wrapper.cpp OutdatedShow resolvedHide resolved

QuLogic force-pushed thetext-language branch 2 times, most recently from3c188df to931423bCompare

May 13, 2025 03:28

QuLogic force-pushed thetext-language branch from931423b to46c6239Compare

May 22, 2025 20:31

github-actionsbot added topic: mplot3d status: needs rebase and removed status: needs rebase labels

Aug 27, 2025

QuLogic commented

Aug 27, 2025

View reviewed changes

src/ft2font.cpp Outdated


		if (languages.has_value()) {
		for (auto & [lang_str, start, end] : languages.value()) {
		if (!raqm_set_language(rq, lang_str.c_str(), start, end)) {

Copy link

MemberAuthor

QuLogicAug 27, 2025•
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

This function actually takes a length, not an end location; I'm not sure which one we should accept (Harfbuzz feature tags use start/end, so maybe that?), but I'll have to update this to the correct naming (the test is setup to match what libraqm says, but the docs say the opposite.)

Copy link

Contributor

anntzerAug 27, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

start-stop looks normal as API to me?

Copy link

MemberAuthor

QuLogicSep 3, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

I agree and have made that change.

github-actionsbot added status: needs rebase and removed status: needs rebase labels

Aug 27, 2025

QuLogic force-pushed thetext-language branch from1858a56 to6d35c9aCompare

September 3, 2025 03:06

github-actionsbot removed topic: mplot3d status: needs rebase labels

Sep 3, 2025

QuLogic moved this fromWaiting for other PR toReady for Review inFont and text overhaul

Sep 3, 2025

QuLogic force-pushed thetext-language branch 3 times, most recently from6fc2dee to6ef55edCompare

September 3, 2025 03:22

Copy link

MemberAuthor

QuLogic commentedSep 3, 2025•
edited
Loading

Also extended the tests a bit to ensure that the results are as expected and fixed the fallback to thercParam as well.

The test image is extracted to a separate commit as it should not be merged yet.

github-actionsbot added the status: needs rebase label

Sep 16, 2025

QuLogic force-pushed thetext-language branch 2 times, most recently fromd8051c2 to886bf64Compare

September 19, 2025 05:55

github-actionsbot removed the status: needs rebase label

Sep 19, 2025

QuLogic force-pushed thetext-language branch 2 times, most recently from0485aee to3ffce36Compare

September 19, 2025 06:33

tacaswell reviewed

Sep 19, 2025

View reviewed changes

doc/release/next_whats_new/text_language.rst Outdated

Comment on lines 35 to 36

		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',

Copy link

Member

tacaswellSep 19, 2025•
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others.Learn more.

Super picky change to match the example ordering to the text ordering:

Suggested change

	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',
	fig.text(0, 0.1, f'Inari Sámi: {char}', fontsize=40, language='smn')
	fig.text(1, 0.1, f'English: {char}', fontsize=40, language='en',