{"id":8671,"library":"sphinx-intl","title":"Sphinx Internationalization Utility","description":"sphinx-intl is a utility for Sphinx that simplifies the process of translating documentation. It helps manage `.pot` (Portable Object Template) and `.po` (Portable Object) files, making it easier to extract translatable messages, update translations, and build translated versions of Sphinx projects. The current version is 2.3.2, and it typically sees a few releases per year, keeping pace with Python and Sphinx updates.","status":"active","version":"2.3.2","language":"en","source_language":"en","source_url":"https://github.com/sphinx-doc/sphinx-intl","tags":["Sphinx","internationalization","i18n","l10n","documentation","gettext"],"install":[{"cmd":"pip install sphinx-intl","lang":"bash","label":"Install latest version"}],"dependencies":[{"reason":"Sphinx-intl is an extension and utility for Sphinx and requires Sphinx to be installed and used effectively.","package":"sphinx","optional":false}],"imports":[],"quickstart":{"code":"import os\nimport shutil\nimport subprocess\nimport tempfile\n\n# Create a temporary directory for the Sphinx project\ntemp_dir = tempfile.mkdtemp()\nprint(f\"Working in temporary directory: {temp_dir}\")\n\ntry:\n    project_dir = os.path.join(temp_dir, \"myproject\")\n    os.makedirs(project_dir)\n\n    # 1. Create a minimal conf.py\n    conf_content = '''\nimport os\nimport sys\nsys.path.insert(0, os.path.abspath('.'))\n\nproject = 'My Translated Project'\ncopyright = '2024, Author'\nextensions = []\nhtml_theme = 'alabaster'\n'''\n    with open(os.path.join(project_dir, \"conf.py\"), \"w\") as f:\n        f.write(conf_content)\n\n    # 2. Create a minimal index.rst with translatable content\n    index_content = '''\n.. _index:\n\nWelcome to My Translated Project\n================================\n\n.. rst-class:: special\n\nThis is a paragraph that needs translation.\n\nAnother paragraph.\n'''\n    with open(os.path.join(project_dir, \"index.rst\"), \"w\") as f:\n        f.write(index_content)\n\n    # 3. Generate POT files using sphinx-build\n    print(\"\\n--- Generating .pot files ---\")\n    gettext_output_dir = os.path.join(project_dir, \"_build\", \"gettext\")\n    subprocess.run([\"sphinx-build\", \"-b\", \"gettext\", project_dir, gettext_output_dir], check=True, capture_output=True, text=True)\n\n    # 4. Initialize locale directory for a target language (e.g., French)\n    print(\"\\n--- Initializing French locale ---\")\n    locale_dir = os.path.join(project_dir, \"_build\", \"locale\")\n    subprocess.run([\"sphinx-intl\", \"init\", \"-l\", \"fr\", \"-d\", locale_dir, \"-p\", gettext_output_dir], check=True, capture_output=True, text=True)\n\n    # 5. Update PO files (no changes yet, but good practice)\n    print(\"\\n--- Updating PO files (no changes expected yet) ---\")\n    subprocess.run([\"sphinx-intl\", \"update\", \"-l\", \"fr\", \"-d\", locale_dir, \"-p\", gettext_output_dir], check=True, capture_output=True, text=True)\n\n    # Simulate manual translation: modify the .po file\n    po_file_path = os.path.join(locale_dir, \"fr\", \"LC_MESSAGES\", \"index.po\")\n    if os.path.exists(po_file_path):\n        with open(po_file_path, \"r\") as f:\n            po_content = f.read()\n        po_content = po_content.replace(\n            'msgid \"This is a paragraph that needs translation.\"',\n            'msgid \"This is a paragraph that needs translation.\"\\nmsgstr \"Ceci est un paragraphe à traduire.\"\n        )\n        po_content = po_content.replace(\n            'msgid \"Another paragraph.\"',\n            'msgid \"Another paragraph.\"\\nmsgstr \"Un autre paragraphe.\"\n        )\n        with open(po_file_path, \"w\") as f:\n            f.write(po_content)\n        print(f\"--- Translated {po_file_path} ---\")\n    else:\n        print(f\"Error: {po_file_path} not found.\")\n\n    # 6. Build MO files from PO files using sphinx-intl build\n    print(\"\\n--- Building MO files from PO files ---\")\n    subprocess.run([\"sphinx-intl\", \"build\", \"-d\", locale_dir], check=True, capture_output=True, text=True)\n\n    # 7. Build HTML output for the translated language\n    print(\"\\n--- Building translated HTML documentation ---\")\n    html_output_dir_fr = os.path.join(project_dir, \"_build\", \"html\", \"fr\")\n    subprocess.run([\"sphinx-build\", \"-b\", \"html\", \"-D\", \"language=fr\", project_dir, html_output_dir_fr], check=True, capture_output=True, text=True)\n\n    print(f\"\\nSuccessfully built translated documentation in: {html_output_dir_fr}\")\n    print(\"Check the generated HTML files, e.g., _build/html/fr/index.html\")\n\nexcept subprocess.CalledProcessError as e:\n    print(f\"Error executing command: {e.cmd}\")\n    print(f\"Return code: {e.returncode}\")\n    print(f\"Stdout:\\n{e.stdout}\")\n    if e.stderr:\n        print(f\"Stderr:\\n{e.stderr}\")\nexcept Exception as e:\n    print(f\"An unexpected error occurred: {e}\")\nfinally:\n    # Clean up the temporary directory\n    print(f\"\\nCleaning up temporary directory: {temp_dir}\")\n    shutil.rmtree(temp_dir)","lang":"python","description":"This quickstart demonstrates the core workflow of sphinx-intl using a temporary Sphinx project. It covers generating `.pot` files, initializing a locale, updating `.po` files, simulating translation, building `.mo` files, and finally building the translated HTML output."},"warnings":[{"fix":"Upgrade your Python environment to 3.9 or newer. If this is not possible, pin `sphinx-intl<2.3.0` in your project's dependencies.","message":"sphinx-intl dropped support for Python versions older than 3.9 in version 2.3.0. Projects using older Python versions will need to upgrade their Python environment or stick to an older sphinx-intl release.","severity":"breaking","affected_versions":">=2.3.0"},{"fix":"Upgrade to sphinx-intl 2.3.2 or newer to ensure `locale_dirs` is correctly honored when provided via `conf.py` with the `-c` option. Verify `locale_dirs` in your `conf.py` and potentially use the `-d` option explicitly with `sphinx-intl` commands.","message":"Prior to version 2.3.2, sphinx-intl's `update` command might not have correctly respected the `locale_dirs` setting when specified via `-c conf.py`. This could lead to `.po` files being generated or updated in unexpected locations.","severity":"gotcha","affected_versions":"<2.3.2"},{"fix":"If using Transifex and upgrading from versions significantly older than 2.2.0, review your `.tx/config` and test translation workflows carefully. For new projects or upgrades, 2.2.0 and newer should provide consistent `resource_name` behavior.","message":"The behavior of `resource_name` in `.tx/config` files (used for Transifex integration) changed before 2.1.0 and was explicitly preserved to pre-2.1.0 behavior in 2.2.0. Users upgrading from very old versions might encounter unexpected resource naming if relying on Transifex.","severity":"gotcha","affected_versions":"2.1.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Upgrade your Python environment to version 3.9 or newer, or install an older compatible version of sphinx-intl (e.g., `pip install 'sphinx-intl<2.3.0'`).","cause":"Your Python version is too old for the installed or requested version of sphinx-intl.","error":"ERROR: Package 'sphinx-intl' requires a different Python: X.Y.Z not in '>=3.9'"},{"fix":"Ensure sphinx-intl is installed in your active Python environment (`pip install sphinx-intl`) and that your environment's `Scripts` or `bin` directory is correctly included in your system's PATH.","cause":"The `sphinx-intl` command-line tool is not installed or not available in your system's PATH.","error":"sphinx-intl: command not found"},{"fix":"Ensure the target locale directory exists before running `sphinx-intl` commands, or create it manually (e.g., `mkdir -p _build/locale`). The `init` command usually creates the initial structure, but `update` or `build` expect it to be present.","cause":"The directory specified with `-d` or `--locale-dir` does not exist. `sphinx-intl` requires this directory for `.po` and `.mo` files.","error":"sphinx-intl: error: argument -d/--locale-dir: directory not found: '_build/locale'"},{"fix":"First, ensure `sphinx-build -b gettext ...` has been run successfully to generate `.pot` files in the specified directory. Then, verify that the `--pot-dir` argument points to the correct location.","cause":"The path provided to the `-p` or `--pot-dir` option either does not exist or contains no `.pot` (Portable Object Template) files.","error":"WARNING: No .pot files found in the specified path: _build/gettext"}]}