@@ -1,5 +1,3 @@
-# This starter workflow is for a CMake project running on multiple platforms. There is a different starter workflow if you just want a single platform.
-# See: https://github.com/actions/starter-workflows/blob/main/ci/cmake-single-platform.yml
 name: CMake on multiple platforms
 
 on:
@@ -13,17 +11,15 @@ jobs:
     runs-on: ${{ matrix.os }}
 
     strategy:
-      # Set fail-fast to false to ensure that feedback is delivered for all matrix combinations. Consider changing this to true when your workflow is stable.
+      # Keep fail-fast off so every platform reports independently.
       fail-fast: false
 
-      # Set up a matrix to run the following 3 configurations:
-      # 1. <Windows, Release, latest MSVC compiler toolchain on the default runner image, default generator>
-      # 2. <Linux, Release, latest GCC compiler toolchain on the default runner image, default generator>
-      # 3. <Linux, Release, latest Clang compiler toolchain on the default runner image, default generator>
-      #
-      # To add more build types (Release, Debug, RelWithDebInfo, etc.) customize the build_type list.
+      # Matrix:
+      #   Windows  — MSVC (cl) only; zlib via vendored header, iconv via Win32 API
+      #   Linux    — GCC and Clang; zlib + iconv from system glibc
+      #   macOS    — Apple Clang; zlib + iconv from system SDK (no extra packages)
       matrix:
-        os: [ubuntu-latest, windows-latest]
+        os: [ubuntu-latest, windows-latest, macos-latest]
         build_type: [Release]
         c_compiler: [gcc, clang, cl]
         include:
@@ -36,40 +32,58 @@ jobs:
           - os: ubuntu-latest
             c_compiler: clang
             cpp_compiler: clang++
+          - os: macos-latest
+            c_compiler: clang
+            cpp_compiler: clang++
         exclude:
           - os: windows-latest
             c_compiler: gcc
           - os: windows-latest
             c_compiler: clang
           - os: ubuntu-latest
             c_compiler: cl
+          - os: macos-latest
+            c_compiler: gcc
+          - os: macos-latest
+            c_compiler: cl
 
     steps:
     - uses: actions/checkout@v4
 
+    # ── Platform dependencies ─────────────────────────────────────────────────
+    # Ubuntu: zlib development headers (iconv is part of glibc — no extra pkg).
+    # macOS / Windows: zlib and iconv are available in the SDK / Win32 API; no
+    # extra installation required.
+    - name: Install dependencies (Ubuntu)
+      if: runner.os == 'Linux'
+      run: sudo apt-get update -qq && sudo apt-get install -y zlib1g-dev
+
+    # ── Build ─────────────────────────────────────────────────────────────────
     - name: Set reusable strings
-      # Turn repeated input strings (such as the build output directory) into step outputs. These step outputs can be used throughout the workflow file.
       id: strings
       shell: bash
       run: |
         echo "build-output-dir=${{ github.workspace }}/build" >> "$GITHUB_OUTPUT"
 
     - name: Configure CMake
-      # Configure CMake in a 'build' subdirectory. `CMAKE_BUILD_TYPE` is only required if you are using a single-configuration generator such as make.
-      # See https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html?highlight=cmake_build_type
+      # BUILD_PYTHON_BINDINGS=OFF: Python wheel building is handled by the
+      # separate python-publish workflow; keeping it off avoids pybind11
+      # dependency noise in the core C++ CI.
       run: >
         cmake -B ${{ steps.strings.outputs.build-output-dir }}
         -DCMAKE_CXX_COMPILER=${{ matrix.cpp_compiler }}
         -DCMAKE_C_COMPILER=${{ matrix.c_compiler }}
         -DCMAKE_BUILD_TYPE=${{ matrix.build_type }}
+        -DBUILD_PYTHON_BINDINGS=OFF
         -S ${{ github.workspace }}
 
     - name: Build
-      # Build your program with the given configuration. Note that --config is needed because the default Windows generator is a multi-config generator (Visual Studio generator).
       run: cmake --build ${{ steps.strings.outputs.build-output-dir }} --config ${{ matrix.build_type }}
 
+    # ── Test ──────────────────────────────────────────────────────────────────
     - name: Test
       working-directory: ${{ steps.strings.outputs.build-output-dir }}
-      # Execute tests defined by the CMake configuration. Note that --build-config is needed because the default Windows generator is a multi-config generator (Visual Studio generator).
-      # See https://cmake.org/cmake/help/latest/manual/ctest.1.html for more detail
-      run: ctest --build-config ${{ matrix.build_type }}
+      # --output-on-failure prints the full test output when any test fails,
+      # making it straightforward to diagnose encoding or parsing regressions
+      # across the three platforms without inspecting runner logs manually.
+      run: ctest --build-config ${{ matrix.build_type }} --output-on-failure
@@ -26,17 +26,37 @@ jobs:
       - name: Build wheels
         uses: pypa/cibuildwheel@v2.22.0
         env:
-          # CPython 3.8 – 3.14 only; skip PyPy (not tested with this extension)
-          CIBW_BUILD: cp38-* cp39-* cp310-* cp311-* cp312-* cp313-* cp314-*
-          # Skip musl/Alpine — system zlib may not be present in all musl images
+          # CPython 3.9 – 3.14; skip PyPy (not validated with this extension).
+          # Python 3.8 reached EOL October 2024 and is no longer built.
+          CIBW_BUILD: cp39-* cp310-* cp311-* cp312-* cp313-* cp314-*
+
+          # Skip musllinux (Alpine / musl libc) on all architectures.
+          # Two runtime dependencies are unavailable in the default musl images:
+          #   • zlib development headers  (needed at build time)
+          #   • iconv (encoding transcoding) — musl libc does not include iconv;
+          #     a separate libiconv package would be required.
+          # Re-enable and add a CIBW_BEFORE_BUILD step if musl support is needed.
           CIBW_SKIP: "*-musllinux_*"
-          # macOS: build both Intel and Apple-Silicon wheels
+
+          # macOS: build both Intel and Apple-Silicon wheels in a single job via
+          # cross-compilation (no separate runner needed for arm64).
           CIBW_ARCHS_MACOS: x86_64 arm64
-          # Linux: x86_64 only (add aarch64 later via QEMU if needed)
+
+          # Linux manylinux: x86_64 only.
+          # Add aarch64 later via QEMU (CIBW_ARCHS_LINUX: x86_64 aarch64 +
+          # CIBW_BEFORE_ALL_LINUX steps) if an ARM release is needed.
           CIBW_ARCHS_LINUX: x86_64
-          # Windows: 64-bit only
+
+          # Windows: 64-bit only.
           CIBW_ARCHS_WINDOWS: AMD64
 
+          # manylinux pre-build: ensure zlib development headers are present.
+          # iconv is part of glibc in all manylinux images — no extra install.
+          CIBW_BEFORE_BUILD_LINUX: yum install -y zlib-devel || apt-get install -y zlib1g-dev || true
+
+          # macOS pre-build: zlib and iconv are in the Xcode SDK; no extra step.
+          # Windows: zlib is vendored (vendor/zlib/zlib.h); iconv uses Win32 API.
+
       - uses: actions/upload-artifact@v4
         with:
           name: cibw-wheels-${{ matrix.os }}
@@ -54,10 +74,11 @@ jobs:
         with:
           python-version: "3.x"
 
+      - name: Install build frontend
+        run: python -m pip install build
+
       - name: Build sdist
-        run: |
-          python -m pip install build
-          python -m build --sdist
+        run: python -m build --sdist
 
       - uses: actions/upload-artifact@v4
         with:
@@ -71,7 +92,7 @@ jobs:
     needs: [build-wheels, build-sdist]
 
     permissions:
-      # Required for OIDC Trusted Publishing — no API token needed
+      # Required for OIDC Trusted Publishing — no API token needed.
       id-token: write
 
     environment:
 
@@ -9,4 +9,6 @@ BUILDING.md
 /build
 .pypirc
 /build_mingw64
-/build_msvc
+/build_msvc
+/dist
+/out
@@ -1,5 +1,5 @@
 cmake_minimum_required(VERSION 3.15)
-project(docx_comment_parser VERSION 1.1.1 LANGUAGES CXX)
+project(docx_comment_parser VERSION 1.1.2 LANGUAGES CXX)
 
 # ─── Policy: normalise install() DESTINATION paths (fixes CMP0177 warning) ───
 if(POLICY CMP0177)
@@ -32,6 +32,14 @@ if(NOT MSVC)
   find_package(ZLIB REQUIRED)
 endif()
 
+# ─── iconv (encoding transcoding) ─────────────────────────────────────────────
+# Windows uses the native MultiByteToWideChar/WideCharToMultiByte APIs (no
+# extra library).  On Linux/macOS iconv is typically part of the C library; on
+# musl or standalone environments a separate libiconv may be needed.
+if(NOT WIN32)
+  find_package(Iconv QUIET)  # sets Iconv::Iconv; harmless no-op when built-in
+endif()
+
 # ─── Common compile options helper ────────────────────────────────────────────
 # Applied to every target that compiles the library sources.
 function(docx_apply_compile_options target)
@@ -61,6 +69,9 @@ function(docx_link_platform_libs target)
   target_link_libraries(${target} PRIVATE
       $<$<NOT:$<CXX_COMPILER_ID:MSVC>>:ZLIB::ZLIB>
   )
+  if(NOT WIN32 AND Iconv_FOUND AND NOT Iconv_IS_BUILT_IN)
+    target_link_libraries(${target} PRIVATE Iconv::Iconv)
+  endif()
   if(MINGW AND _has_pthread_h)
     target_link_libraries(${target} PRIVATE -lpthread)
   endif()
 
@@ -4,7 +4,7 @@ A C++17 shared library that extracts every piece of comment metadata from `.docx
 
 [![Tests](https://img.shields.io/badge/tests-38%20passing-brightgreen)](#testing)
 [![C++17](https://img.shields.io/badge/C%2B%2B-17-blue)](#building-the-shared-library)
-[![Python ≥ 3.8](https://img.shields.io/badge/python-%E2%89%A53.8-blue)](#python-quick-start)
+[![Python ≥ 3.9](https://img.shields.io/badge/python-%E2%89%A53.8-blue)](#python-quick-start)
 [![License: MIT](https://img.shields.io/badge/license-MIT-green)](#license)
 
 ---
@@ -618,17 +618,39 @@ Expected output:
 Test fixture: /tmp/test_docx_parser_fixture.docx
 
 === test_basic_parsing ===
+
 === test_threading ===
+
 === test_done_flag ===
+
 === test_anchor_text ===
+
 === test_by_author ===
+
 === test_stats ===
+
 === test_root_comments ===
+
 === test_batch_parser ===
+
 === test_missing_file ===
 
+=== test_encoding_utf8_bom ===
+
+=== test_encoding_utf16le ===
+
+=== test_encoding_utf16be ===
+
+=== test_encoding_utf32le ===
+
+=== test_encoding_windows1252 ===
+
+=== test_encoding_iso8859_1 ===
+
+=== test_encoding_numeric_entities ===
+
 ──────────────────────────────
-Results: 38 passed, 0 failed
+Results: 66 passed, 0 failed
 ```
 
 The test binary exits with code `0` on full pass, `1` on any failure.
@@ -637,6 +659,41 @@ The test binary exits with code `0` on full pass, `1` on any failure.
 
 ## Changelog
 
+### v1.1.2 — Added multiple enconding support
+
+Included multiple text enconding support for a wide range of encondings. Updated unit tests for the new text enconding functionality.
+
+#### `src/xml_parser.cpp` — Added a complete encoding transcoding layer before the XML parser:
+
+`extract_xml_encoding_decl()` — scans the XML prolog for encoding="..."
+
+`detect_encoding()` — BOM detection (UTF-8/16/32 LE/BE) takes precedence, falls back to the XML declaration
+
+`utf16_to_utf8()` / `utf32_to_utf8()` — built-in converters (no platform dependency) with correct surrogate-pair handling
+
+**Windows path:** `win_mbcs_to_utf8()` via `MultiByteToWideChar` + `WideCharToMultiByte`; maps 60+ encoding names to Windows codepage numbers (all Windows-125x, ISO-8859-1..16, Asian, Cyrillic, Thai, OEM codepages)
+
+**Linux/macOS path:** `iconv_convert()` via `iconv(3)` with the same name alias table; handles `E2BIG`/`EILSEQ`/`EINVAL` gracefully
+`transcode_to_utf8()` — public entry point, called at the start of `sax_parse()` so all parsing paths (DOM and SAX) go through it automatically
+
+#### `include/xml_parser.h` — Exposed transcode_to_utf8() as a public API with full docstring.
+
+#### `CMakeLists.txt` — Added `find_package(Iconv QUIET)` for non-Windows targets; links `Iconv::Iconv` only when it's a separate library (not built into libc).
+
+#### `tests/test_docx_parser.cpp` — Added 7 encoding tests (66 total, all green):
+
+`test_encoding_utf8_bom` — UTF-8 BOM is silently stripped
+
+`test_encoding_utf16le` / `test_encoding_utf16be` — BOM-detected UTF-16
+
+`test_encoding_utf32le` — BOM-detected UTF-32
+
+`test_encoding_windows1252` — `encoding="windows-1252"` with ç, é, ä in content
+
+`test_encoding_iso8859_1` — `encoding="ISO-8859-1"` with é, ñ
+
+`test_encoding_numeric_entities` — `&#x4E2D;` (Chinese) and `&#233;` (é) references
+
 ### v1.1.0 — Inflate fix and zero-dependency MSVC support
 
 **Public API:** unchanged. Existing code does not need modification.
 
@@ -96,4 +96,25 @@ std::string node_text(const XmlNode& node);
 /** Truncate a string to max_bytes (at a UTF-8 boundary). */
 std::string truncate_utf8(const std::string& s, std::size_t max_bytes);
 
+/**
+ * Convert an arbitrary-encoded XML byte stream to UTF-8.
+ *
+ * Detects encoding via BOM (UTF-8/16/32 LE/BE) and/or the XML declaration's
+ * encoding="..." attribute.  Supported encodings include:
+ *   - Unicode:  UTF-8, UTF-16 LE/BE, UTF-32 LE/BE (with or without BOM)
+ *   - European: ISO-8859-1..16, Windows-125x, KOI8-R/U, IBM OEM codepages
+ *   - Asian:    Shift-JIS, GBK/GB2312, GB18030, Big5, EUC-JP/KR/CN,
+ *               ISO-2022-JP/KR/CN
+ *   - Other:    TIS-620 (Thai), US-ASCII, and any encoding supported by the
+ *               platform's iconv (Linux/macOS) or MultiByteToWideChar (Windows).
+ *
+ * Returns the UTF-8 string.  If the input is already valid UTF-8 (the common
+ * case for OOXML), a copy is returned without any conversion overhead beyond
+ * a BOM strip if needed.
+ *
+ * A trailing NUL byte appended by callers for parser safety is silently
+ * stripped before conversion.
+ */
+std::string transcode_to_utf8(const char* data, std::size_t len);
+
 } // namespace docx
@@ -7,10 +7,10 @@ build-backend = "scikit_build_core.build"
 
 [project]
 name = "docx-comment-parser"
-version = "1.1.1"
+version = "1.1.2"
 description = "Fast C++ library for extracting comment metadata from .docx files"
 readme = "README.md"
-requires-python = ">=3.8"
+requires-python = ">=3.9"
 authors = [{name = "nick-developer"}]
 classifiers = [
     "Programming Language :: Python :: 3",
 
@@ -123,7 +123,7 @@ def _is_mingw() -> bool:
 
 setup(
     name="docx-comment-parser",
-    version="1.1.1",
+    version="1.1.2",
     author="nick-developer",
     description="Fast C++ library for extracting comment metadata from .docx files",
     long_description=(
@@ -132,7 +132,7 @@ def _is_mingw() -> bool:
         else ""
     ),
     ext_modules=[ext],
-    python_requires=">=3.8",
+    python_requires=">=3.9",
     classifiers=[
         "Programming Language :: Python :: 3",
         "Programming Language :: C++",