feat(conversion): add PDF to EPUB/AZW3 conversion support and settings (#5434)

# Description of Changes


This pull request introduces support for converting PDF files to eBook
formats (EPUB and AZW3) in the frontend. It adds new user interface
options for PDF-to-eBook conversion, updates the conversion logic and
parameters, and ensures the new formats are integrated into the
conversion matrix and endpoints. The most important changes are grouped
below:

**PDF to eBook (EPUB/AZW3) Conversion Support**

* Added a new `ConvertToEpubSettings` component that provides UI
controls for PDF-to-eBook options, including chapter detection, target
device selection, and output format.
(`frontend/src/core/components/tools/convert/ConvertToEpubSettings.tsx`)
* Updated `ConvertSettings` to render the new eBook options when
converting from PDF to EPUB or AZW3, and set default values for these
options.
(`frontend/src/core/components/tools/convert/ConvertSettings.tsx`)
* Extended the `ConvertParameters` interface and default parameters to
include `epubOptions` for the new settings.
(`frontend/src/core/hooks/tools/convert/useConvertParameters.ts`)

**Conversion Logic and API Integration**

* Updated the conversion endpoints, endpoint names, and conversion
matrix to support PDF-to-EPUB/AZW3 conversions.
(`frontend/src/core/constants/convertConstants.ts`)
* Modified the conversion operation logic to handle `epubOptions` and
ensure that PDF-to-eBook conversions process each file separately and
send the correct options to the backend.
(`frontend/src/core/hooks/tools/convert/useConvertOperation.ts`)
**Localization and Tool Registry Updates**

* Added localization strings for the new eBook conversion options.
(`frontend/public/locales/en-GB/translation.toml`)
* Registered the new PDF-to-eBook operation in the tool catalog and test
helpers. (`frontend/src/core/data/useTranslatedToolRegistry.tsx`,
`frontend/src/core/tests/helpers/conversionEndpointDiscovery.ts`)



<img width="364" height="995" alt="image"
src="https://github.com/user-attachments/assets/c54c50c0-1b86-4074-aef8-b038c6caeb49"
/>

<!--
Please provide a summary of the changes, including:

- What was changed
- Why the change was made
- Any challenges encountered

Closes #(issue_number)
-->

---

## Checklist

### General

- [X] I have read the [Contribution
Guidelines](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/CONTRIBUTING.md)
- [X] I have read the [Stirling-PDF Developer
Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md)
(if applicable)
- [ ] I have read the [How to add new languages to
Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md)
(if applicable)
- [X] I have performed a self-review of my own code
- [X] My changes generate no new warnings

### Documentation

- [ ] I have updated relevant docs on [Stirling-PDF's doc
repo](https://github.com/Stirling-Tools/Stirling-Tools.github.io/blob/main/docs/)
(if functionality has heavily changed)
- [ ] I have read the section [Add New Translation
Tags](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md#add-new-translation-tags)
(for new translation tags only)

### Translations (if applicable)

- [ ] I ran
[`scripts/counter_translation.py`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/docs/counter_translation.md)

### UI Changes (if applicable)

- [X] Screenshots or videos demonstrating the UI changes are attached
(e.g., as comments or direct attachments in the PR)

### Testing (if applicable)

- [X] I have tested my changes locally. Refer to the [Testing
Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/DeveloperGuide.md#6-testing)
for more details.

Signed-off-by: Balázs Szücs <[email protected]>
Co-authored-by: Anthony Stirling <[email protected]>

frontend/src/core/hooks/tools/convert/useConvertOperation.ts

@@ -23,6 +23,8 @@ export const shouldProcessFilesSeparately = (
     (parameters.fromExtension === 'pdf' && ['txt', 'rtf', 'csv'].includes(parameters.toExtension)) ||
   // PDF to CBR conversions (each PDF should generate its own archive)
   (parameters.fromExtension === 'pdf' && parameters.toExtension === 'cbr') ||
+    // PDF to EPUB/AZW3 conversions (each PDF should generate its own ebook)
+    (parameters.fromExtension === 'pdf' && ['epub', 'azw3'].includes(parameters.toExtension)) ||
     // PDF to office format conversions (each PDF should generate its own office file)
     (parameters.fromExtension === 'pdf' && isOfficeFormat(parameters.toExtension)) ||
     // Office files to PDF conversions (each file should be processed separately via LibreOffice)
@@ -42,7 +44,7 @@ export const shouldProcessFilesSeparately = (
 // Static function that can be used by both the hook and automation executor
 export const buildConvertFormData = (parameters: ConvertParameters, selectedFiles: File[]): FormData => {
   const formData = new FormData();
-  const { fromExtension, toExtension, imageOptions, htmlOptions, emailOptions, pdfaOptions, cbrOptions, pdfToCbrOptions, cbzOptions, cbzOutputOptions, ebookOptions } = parameters;
+  const { fromExtension, toExtension, imageOptions, htmlOptions, emailOptions, pdfaOptions, cbrOptions, pdfToCbrOptions, cbzOptions, cbzOutputOptions, ebookOptions, epubOptions } = parameters;
 
   selectedFiles.forEach(file => {
     formData.append("fileInput", file);
@@ -88,6 +90,10 @@ export const buildConvertFormData = (parameters: ConvertParameters, selectedFile
     formData.append("includeTableOfContents", (ebookOptions?.includeTableOfContents ?? false).toString());
     formData.append("includePageNumbers", (ebookOptions?.includePageNumbers ?? false).toString());
     formData.append("optimizeForEbook", (ebookOptions?.optimizeForEbook ?? false).toString());
+  } else if (fromExtension === 'pdf' && ['epub', 'azw3'].includes(toExtension)) {
+    formData.append("detectChapters", (epubOptions?.detectChapters ?? true).toString());
+    formData.append("targetDevice", epubOptions?.targetDevice ?? 'TABLET_PHONE_IMAGES');
+    formData.append("outputFormat", epubOptions?.outputFormat ?? (toExtension === 'azw3' ? 'AZW3' : 'EPUB'));
   }
 
   return formData;

frontend/src/core/hooks/tools/convert/useConvertParameters.ts

@@ -54,6 +54,11 @@ export interface ConvertParameters extends BaseParameters {
     includePageNumbers: boolean;
     optimizeForEbook: boolean;
   };
+  epubOptions?: {
+    detectChapters: boolean;
+    targetDevice: string;
+    outputFormat: string;
+  };
   isSmartDetection: boolean;
   smartDetectionType: 'mixed' | 'images' | 'web' | 'none';
 }
@@ -105,6 +110,11 @@ export const defaultParameters: ConvertParameters = {
     includePageNumbers: false,
     optimizeForEbook: false,
   },
+  epubOptions: {
+    detectChapters: true,
+    targetDevice: 'TABLET_PHONE_IMAGES',
+    outputFormat: 'EPUB',
+  },
   isSmartDetection: false,
   smartDetectionType: 'none',
 };