使用 pymupdf（fitz）向 pdf 插入古吉拉特语等复杂脚本文字时，若直接调用 `insert_text()` 且未正确配置字体与渲染方式，易出现字符错位、连字断裂（如“રવ્ નિદર”而非“રવિન્દ્ર”），根本原因是 `insert_text()` 不支持 opentype 特性（如 gsub/gpos 表），无法处理印度系文字的上下文连字与元音附标定位。
要可靠渲染古吉拉特语（以及泰米尔语、印地语、孟加拉语等印度系文字），必须避免 page.insert_text()，而应改用 page.insert_htmlbox() —— 这是 PyMuPDF 内置的轻量级 HTML 渲染引擎，底层基于 MuPDF 的 HTML/CSS 解析器，原生支持 Unicode、双向文本（BIDI）、OpenType 字体特性（包括连字、元音位置调整、辅音簇组合），能准确还原复杂脚本的视觉呈现。
✅ 正确做法：使用 insert_htmlbox()
insert_htmlbox() 接收 HTML 字符串和一个矩形区域（rect），自动选择系统或嵌入字体，并启用完整文本整形（shaping）。以下是适配您原始场景的修复版代码：
import fitz
from googletrans import Translator
def add_gujarati_text_to_pdf(pdf_path, output_path, text_to_add):
# 打开现有 PDF（注意：insert_htmlbox 可用于已有文档）
doc = fitz.open(pdf_path)
# 定义插入区域：x0, y0, x1, y1（左上→右下）
# 示例：在第3页（索引2）的 (175, 215) 附近放置一个宽150高40的文本框
rect = fitz.Rect(175, 215, 325, 255) # 宽度=150, 高度=40
for page_num in range(doc.page_count):
if page_num == 2: # 第三页（0-indexed）
page = doc[page_num]
# 构建带内联样式的 HTML（确保字体可读且支持 Gujarati）
html = f'''
{text_to_add}
'''
# 关键：使用 insert_htmlbox 替代 insert_text
page.insert_htmlbox(rect, html)
break
# 启用字体子集化（减小体积，保留所需字符）
doc.subset_fonts()
# 保存并压缩
doc.save(output_path, garbage=3, deflate=True)
doc.close()
# 使用示例
if __name__ == "__main__":
input_pdf_path = "input.pdf"
output_pdf_path = "output_with_gujarati.pdf"
translator = Translator()
result = translator.translate('Ravindra Nakrani', src='en', dest='gu')
gujarati_name = result.text # 如：રવિન્દ્ર નાકરાણી
print("Translated:", gujarati_name)
add_gujarati_text_to_pdf(input_pdf_path, output_pdf_path, gujarati_name)⚠️ 关键注意事项
- 字体选择：insert_htmlbox() 会自动查找系统中已安装的支持古吉拉特语的字体（如 Noto Sans Gujarati、Shruti、Lohit Gujarati）。若目标环境无合适字体，需提前将 .ttf 文件嵌入 PDF（通过 doc.embed_font()），并在 HTML 中指定 font-family。
- 坐标与尺寸：insert_htmlbox() 使用 Rect(x0,y0,x1,y1)，不是 (x,y) 点坐标；务必预留足够高度（≥ fontsize × 1.4）以容纳上下标与连字。
-
HTML 是必需的封装层：即使只插纯文本，也必须包裹在 或 中，并声明 font-family 和 font-size，否则可能回退到不支持的默认字体。
- 不支持 fontfile= 参数：insert_htmlbox() 不接受 fontfile=，字体由 CSS 控制；如需强制使用特定字体文件，请先调用 doc.embed_font("path/to/NotoSansGujarati-Regular.ttf")，再在 HTML 中引用其 PostScript 名（可通过 fitz.Font(fontfile=...) 获取）。
- 性能提示：insert_htmlbox() 比 insert_text() 略慢，但对单次插入完全可忽略；批量插入时建议复用 doc 实例，避免重复解析。
✅ 验证是否成功
生成 PDF 后，用 Adobe Acrobat 或最新版 Chrome 打开，检查：
- “રવિન્દ્ર” 是否显示为连贯字符（િ 正确附着在 ર 下方，ન્ 正确形成辅音簇）；
- 无乱码、空格异常或字符分离现象；
- 文本可被 PDF 阅读器正确复制粘贴为 Unicode 字符串。
通过 insert_htmlbox()，PyMuPDF 能真正实现多语言、多脚本的高质量 PDF 文本注入——这是处理印度系文字、阿拉伯文、希伯来文等复杂书写系统的推荐标准方案。
