{"library":"sphinx-intl","title":"Sphinx Internationalization Utility","type":"library","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.","language":"python","status":"active","last_verified":"Thu Apr 16","install":{"commands":["pip install sphinx-intl"],"cli":{"name":"sphinx-intl","version":"Usage: sphinx-intl [OPTIONS] COMMAND [ARGS]..."}},"imports":[],"auth":{"required":false,"env_vars":[]},"links":{"homepage":null,"github":"https://github.com/sphinx-doc/sphinx-intl","docs":"https://sphinx-intl.readthedocs.io","changelog":null,"pypi":"https://pypi.org/project/sphinx-intl/","npm":null,"openapi_spec":null,"status_page":null,"smithery":null},"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.","tag":null,"tag_description":null,"last_tested":null,"results":[]},"compatibility":null}