You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
In lectures where we have 'text.usetex': True, we need to add the following headers:
# Configure Matplotlib to use pdfLaTeX and CJKutf8
mpl.rcParams.update({
'text.usetex': True,
'text.latex.preamble': r'''
\usepackage{{CJKutf8}}
\usepackage{{amsmath}}
'''
})
# Function to wrap Chinese text in CJK environment
def cjk(text):
return rf'\begin{{CJK}}{{UTF8}}{{gbsn}}{text}\end{{CJK}}'
Then apply the cjk function to the Chinese character to the figure plotting matplotlib.
Decision: move the zh edition off usetex rather than adopt the CJKutf8 + cjk() wrapper
Revisiting this during the 2026-07-18/19 resync wave. The scope turned out to be tiny and precise: exactly two lectures in the whole edition use text.usetex=True — kalman_2 and two_auctions (verified by grepping the English source, since a resync only inherits usetex from upstream). So this issue affects those two files and nothing else.
The wave gave us direct evidence of how fragile the usetex + cjk() approach is. On kalman_2 alone we hit three distinct failures: the resync dropped the def cjk() helper (→ NameError in every figure cell); once the helper was restored, the LaTeX preamble was missing amsfonts, so upstream's rewritten \mathbb{E}[...] titles raised "Undefined control sequence" and fig.tight_layout() crashed; and every one of these was invisible until a cold, uncached build — a cached green checkmark hid a broken lecture. two_auctions failed separately because the resync brought upstream's usetex=True but translated the labels to Chinese without wrapping them, so LaTeX errored on Unicode character 估 (U+4F30).
The root cause is structural: usetex requires the cjk() def to be present, every Chinese label to be wrapped, the preamble to load every LaTeX package the labels' math uses, and a LaTeX toolchain in CI — and the resync engine drops these i18n adaptations on every run (the QuantEcon/action-translation#107 class), so each future sync re-breaks these lectures and needs careful manual repair.
We weighed keeping usetex (this issue's original prescription) against dropping it and rendering via the font-manager + mathtext, which is what the other ~38 lectures already do. Dropping usetex wins on every axis that matters here: it removes the fragile machinery and the cache-masked failure mode, it makes the resync repair trivial (restore the one-line font block, same as everywhere else), it keeps these two lectures consistent with the rest of the edition, and it even makes the Chinese in plot labels use Source Han Serif (the edition's font) instead of the CJK LaTeX gbsn font. The only thing usetex bought us was marginally nicer LaTeX math in two lectures' plot labels — and the math involved is simple ($\mathbb{E}[y_t|y^{t-1}]$, $v_i$, $b_i$), all of which mathtext renders natively (mathtext supports \mathbb). That aesthetic edge is not worth a recurring, fragile maintenance burden on an edge case.
Standard going forward: the zh edition renders Chinese via plt.rcParams['font.family'] = ['Source Han Serif SC'] and math via mathtext; avoid text.usetex in translated lectures. When a resync pulls in an upstream lecture that sets usetex, drop the usetex config rather than adding CJK machinery.
The zh edition now renders Chinese via font.family (Source Han Serif) and math via mathtext across all lectures, with no lecture on the usetex path. Standard for future resyncs: when upstream sets text.usetex, drop it rather than adding CJK machinery.
Activity
mmcky commentedon Jul 19, 2026
Decision: move the zh edition off
usetexrather than adopt the CJKutf8 +cjk()wrapperRevisiting this during the 2026-07-18/19 resync wave. The scope turned out to be tiny and precise: exactly two lectures in the whole edition use
text.usetex=True—kalman_2andtwo_auctions(verified by grepping the English source, since a resync only inherits usetex from upstream). So this issue affects those two files and nothing else.The wave gave us direct evidence of how fragile the usetex +
cjk()approach is. Onkalman_2alone we hit three distinct failures: the resync dropped thedef cjk()helper (→NameErrorin every figure cell); once the helper was restored, the LaTeX preamble was missingamsfonts, so upstream's rewritten\mathbb{E}[...]titles raised "Undefined control sequence" andfig.tight_layout()crashed; and every one of these was invisible until a cold, uncached build — a cached green checkmark hid a broken lecture.two_auctionsfailed separately because the resync brought upstream'susetex=Truebut translated the labels to Chinese without wrapping them, so LaTeX errored onUnicode character 估 (U+4F30).The root cause is structural:
usetexrequires thecjk()def to be present, every Chinese label to be wrapped, the preamble to load every LaTeX package the labels' math uses, and a LaTeX toolchain in CI — and the resync engine drops these i18n adaptations on every run (the QuantEcon/action-translation#107 class), so each future sync re-breaks these lectures and needs careful manual repair.We weighed keeping usetex (this issue's original prescription) against dropping it and rendering via the font-manager + mathtext, which is what the other ~38 lectures already do. Dropping usetex wins on every axis that matters here: it removes the fragile machinery and the cache-masked failure mode, it makes the resync repair trivial (restore the one-line font block, same as everywhere else), it keeps these two lectures consistent with the rest of the edition, and it even makes the Chinese in plot labels use Source Han Serif (the edition's font) instead of the CJK LaTeX gbsn font. The only thing usetex bought us was marginally nicer LaTeX math in two lectures' plot labels — and the math involved is simple (
$\mathbb{E}[y_t|y^{t-1}]$,$v_i$,$b_i$), all of which mathtext renders natively (mathtext supports\mathbb). That aesthetic edge is not worth a recurring, fragile maintenance burden on an edge case.Standard going forward: the zh edition renders Chinese via
plt.rcParams['font.family'] = ['Source Han Serif SC']and math via mathtext; avoidtext.usetexin translated lectures. When a resync pulls in an upstream lecture that setsusetex, drop the usetex config rather than adding CJK machinery.Fixes landing this:
two_auctions— usetex dropped, in the resync wave PR [action-translation] resync: two_auctions.md #156.kalman_2— usetex dropped and the 13cjk()calls unwrapped, in kalman_2: drop usetex, render CJK + math via font-manager + mathtext (#22) #181.Will close this once both are merged and verified green.
mmcky commentedon Jul 19, 2026
cc: @HumphreyYang
kalman_2: drop usetex, render CJK+math via font-manager + mathtext (#181
mmcky commentedon Jul 19, 2026
Both usetex lectures are now converted and merged green, so this is resolved:
two_auctions— usetex dropped ([action-translation] resync: two_auctions.md #156, merged)kalman_2— usetex dropped, 13cjk()calls unwrapped,\mathbb{E}[...]titles rendering via mathtext (kalman_2: drop usetex, render CJK + math via font-manager + mathtext (#22) #181, merged; the build confirmed the\mathbbglyph renders under mathtext)The zh edition now renders Chinese via
font.family(Source Han Serif) and math via mathtext across all lectures, with no lecture on the usetex path. Standard for future resyncs: when upstream setstext.usetex, drop it rather than adding CJK machinery.FIX: execution and doc failures from the Anaconda 2026.07 cache build (…
CI: align build safety with the English source repo (closes #184) (#185)