如何通过Sphinx与sphinx-intl隐藏标记为忽略的未翻译内容

嘿，我之前刚好碰到过一模一样的需求，给你两个实用的解决思路，按需选就行：

方案一：直接在源RST文件中用条件指令控制（最省心） #

这个方法最直接，从源头就把不需要翻译的内容限制在母语版本里，根本不会进入PO文件，不用后续处理。

只需要把仅母语用户需要的内容用Sphinx的only指令包裹，指定只有目标语言（比如英语）时才显示：

Important content

.. only:: language == 'en'
   :orphan:

   Content which is only relevant in english

• 非英语版本编译时，这段内容会被直接跳过，不会出现在最终文档里
• 也不会被sphinx-intl提取到PO文件中，彻底避免翻译问题

方案二：利用PO文件标记+自定义Sphinx扩展（适合已有大量PO内容的场景） #

如果已经把内容放进PO文件了，想通过ignore标记来控制隐藏，可以这么做：

步骤1：修改PO文件的标记和翻译内容 #

给需要忽略的条目添加ignore标记，并且把msgstr设为空字符串（别留特殊占位符，空字符串更稳妥）：

#: ../../myfile.rst:26
msgid "Important content"
msgstr "Contenu important"

#: ../../myfile.rst:28
#, ignore
msgid "Content which is only relevant in english"
msgstr ""

步骤2：编写自定义Sphinx扩展 #

写一个简单的扩展，重载翻译函数，让带有ignore标记且msgstr为空的内容直接返回空，而不是回退显示原文。

创建一个名为ignore_translations.py的文件，内容如下：

from sphinx.util import logging
from sphinx.locale import _

logger = logging.getLogger(__name__)

def setup(app):
    # 保存原有的翻译函数
    original_gettext = app.builder.templates.environment.gettext
    
    def custom_gettext(message):
        # 获取当前语言的翻译实例
        from sphinx.intl.translation import get_translation
        trans = get_translation(app.config.language)
        # 查找对应的翻译条目
        entry = trans.gettext_entry(message)
        
        # 检查是否有ignore标记且翻译内容为空
        if entry and 'ignore' in entry.flags and not entry.msgstr:
            return ""
        # 其他情况用原逻辑
        return original_gettext(message)
    
    # 替换模板环境中的翻译函数
    app.builder.templates.environment.gettext = custom_gettext
    return {'version': '0.1', 'parallel_read_safe': True}

步骤3：在conf.py中启用扩展 #

把刚才写的扩展添加到Sphinx配置文件的extensions列表里：

extensions = [
    # 你的其他扩展（比如sphinx_rtd_theme等）
    'ignore_translations',
]

这样编译非英语版本时，带有ignore标记的空翻译内容就会被完全隐藏，不会显示原文了。

内容的提问来源于stack exchange，提问作者Fabzi