文档国际化与版本切换

iamai 文档使用 Sphinx 自带 gettext/i18n 能力生成翻译文件，并使用内置 iamai_i18n_versions 扩展在左侧目录栏渲染版本与语言切换器。

维护翻译

默认语言是 zh_CN。翻译文件放在 docs/locales 下。典型流程：

uv run --group docs sphinx-build -b gettext docs docs/_build/gettext
uv run --group docs sphinx-intl update -p docs/_build/gettext -l en
uv run --group docs sphinx-build -D language=en -b html docs docs/_build/html/en

如果本地没有 sphinx-intl，可以临时运行 uv add --group docs sphinx-intl，或者只使用 Sphinx gettext 输出交给翻译平台处理。

配置切换器

切换器的配置位于 docs/conf.py：

iamai_docs_current_version = "dev"
iamai_docs_current_language = "zh_CN"
iamai_docs_versions = [
    {"name": "dev", "label": "Development", "url": "#", "current": True},
    {"name": "latest", "label": "Latest", "url": "/latest/zh_CN/"},
    {"name": "0.1", "label": "0.1", "url": "/0.1/zh_CN/"},
]
iamai_docs_languages = [
    {"name": "zh_CN", "label": "中文", "url": "#", "current": True},
    {"name": "en", "label": "English", "url": "/dev/en/"},
]

url 可以是 #、相对路径、站点根路径或完整 http(s) URL。部署到 GitHub Pages 时， 推荐把不同版本和语言构建到稳定目录，例如 /dev/zh_CN/、/dev/en/、/latest/zh_CN/。

扩展输出

构建完成后，扩展会写入 _static/iamai-docs-switcher-config.js，并加载：

• _static/iamai-docs-switcher.js

• _static/iamai-docs-switcher.css

这三个文件共同渲染左侧目录栏里的切换按钮。它是纯静态实现，不需要后端服务。