Skip to content

Commit a3bef9e

Browse files
committed
docs: add FAQ entry for Chinese character alignment issues
Add comprehensive FAQ entry explaining why Chinese/CJK characters may not align properly and provide solutions including: - UTF-8 encoding configuration - Terminal recommendations by OS - Font suggestions for CJK support - Windows-specific notes and workarounds This helps Chinese developers resolve common display issues when using Rich with CJK content.
1 parent 2770102 commit a3bef9e

File tree

1 file changed

+48
-0
lines changed

1 file changed

+48
-0
lines changed

FAQ.md

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -10,6 +10,7 @@
1010
- [Strange colors in console output.](#strange-colors-in-console-output)
1111
- [Why does content in square brackets disappear?](#why-does-content-in-square-brackets-disappear)
1212
- [Why does emoji break alignment in a Table or Panel?](#why-does-emoji-break-alignment-in-a-table-or-panel)
13+
- [Why do Chinese characters not align properly?](#why-do-chinese-characters-not-align-properly)
1314

1415
<a name="extra-space-not-enough-space-in-jupyter-output"></a>
1516
## Extra space, not enough space, in Jupyter output
@@ -108,6 +109,53 @@ There are also *multiple codepoints* characters, such as country flags, and emoj
108109

109110
Fortunately, most characters will work just fine. But you may have to avoid using the emojis that break alignment. You will get good results if you stick to emoji released on or before version 9 of the Unicode database,
110111

112+
<a name="why-do-chinese-characters-not-align-properly"></a>
113+
## Why do Chinese characters not align properly?
114+
115+
Chinese characters (and other CJK characters) are typically displayed as "wide" characters, taking up two columns in the terminal. This can sometimes cause alignment issues in Tables, Panels, and other containers.
116+
117+
### Solutions
118+
119+
1. **Ensure UTF-8 encoding**: Make sure your terminal and Python environment are using UTF-8 encoding:
120+
121+
```python
122+
from rich.console import Console
123+
console = Console(encoding="utf-8")
124+
```
125+
126+
2. **Use a CJK-compatible terminal**: Some terminals handle CJK characters better than others. Recommended terminals include:
127+
- **Windows**: Windows Terminal (not the legacy cmd.exe)
128+
- **macOS**: iTerm2 or Terminal.app
129+
- **Linux**: GNOME Terminal, Konsole, or Alacritty
130+
131+
3. **Set appropriate fonts**: Use fonts that properly support CJK characters, such as:
132+
- Microsoft YaHei (Windows)
133+
- PingFang SC (macOS)
134+
- Noto Sans CJK (Linux)
135+
136+
4. **Check terminal width calculation**: If you're still seeing alignment issues, you can check how your terminal calculates character widths:
137+
138+
```python
139+
from rich.console import Console
140+
console = Console()
141+
console.print("中文测试") # Should display 4 columns wide
142+
```
143+
144+
5. **Use Rich's `force_terminal` option**: If Rich incorrectly detects your terminal capabilities, you can force true color support:
145+
146+
```python
147+
from rich.console import Console
148+
console = Console(force_terminal=True)
149+
```
150+
151+
### Note on Windows
152+
153+
Windows Terminal supports CJK characters well, but the legacy Windows console (cmd.exe) has limited support. If you must use cmd.exe, you may need to:
154+
- Change the code page to UTF-8: `chcp 65001`
155+
- Use a TrueType font like "SimHei" or "Microsoft YaHei"
156+
157+
For best results on Windows, use Windows Terminal which is available from the Microsoft Store.
158+
111159
<hr>
112160

113161
Generated by [FAQtory](https://github.com/willmcgugan/faqtory)

0 commit comments

Comments
 (0)