subtranslate-ai 0.9.0__tar.gz

subtranslate_ai-0.9.0/CHANGELOG.md

@@ -0,0 +1,79 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+> **Maintainer note:** When releasing a new version, move the entries below from
+> `[Unreleased]` into a new `## [x.y.z] – YYYY-MM-DD` section. Add a link at the
+> bottom of the file comparing the new tag with the previous one.
+
+---
+
+## [Unreleased]
+
+## [0.9.0] - 2026-09-05
+
+### Added
+
+- **Core translation engine** – SRT subtitle translation using LLM providers.
+  Batch translation preserves subtitle indices, timestamps, formatting, and
+  line breaks.
+- **OpenAI provider** – Translation and consistency review via the OpenAI API.
+  Configured with `OPENAI_API_KEY` and optional `OPENAI_MODEL`.
+- **Gemini provider** – Translation and consistency review via the Google Gemini
+  API. Configured with `GEMINI_API_KEY` and optional `GEMINI_MODEL`.
+- **Provider selection** – `--provider openai|gemini` (default: `openai`).
+  Provider names are case-insensitive.
+- **Rolling context** – Each translation batch optionally receives recently
+  accepted translations as read-only guidance, configurable with
+  `--context-size` (default: 10, disable with 0).
+- **Glossary support** – `--glossary PATH` accepts a UTF-8 JSON file of
+  approved source-to-target terminology. Glossary languages must match the CLI
+  source and target languages.
+- **Optional consistency report** – `--consistency-report PATH` triggers a
+  separate advisory review after translation, writing a Markdown findings
+  report. The review never modifies the translated SRT.
+- **Cross-provider review** – `--review-provider` selects an independent
+  provider for consistency review. `--review-model` overrides the review model
+  independently of `--model`.
+- **Standalone review command** – `subtitle-translator review SOURCE TRANSLATED`
+  generates a consistency report from existing SRT files without re-translating.
+  Both files must have matching subtitle indices and timestamps.
+- **Legacy CLI compatibility** – Existing commands using positional SRT path
+  arguments continue to work without a `translate` subcommand.
+- **Automatic retry and resume** – Failed or interrupted translations can be
+  retried; batch progress is preserved across runs.
+- **Output-file safety** – Existing output files and report files are never
+  overwritten by default. Writes use atomic replacement where supported.
+- **`--version` flag** – Reports the installed package version without requiring
+  provider SDKs.
+- **Optional dependency extras** – `openai`, `gemini`, `all`, and `dev` extras
+  allow selective installation of provider SDKs.
+- **Packaging and distribution** – Wheel and source distribution build correctly
+  with all prompt resources and the LICENSE file included.
+- **CI** – GitHub Actions workflow running tests, Ruff, build, distribution
+  verification, and installed-wheel verification across Python 3.11–3.13.
+- **Release automation** – GitHub Actions release workflow using PyPI Trusted
+  Publishing (OIDC); no stored API token required.
+- **Documentation** – README, CONTRIBUTING, SECURITY, CHANGELOG, architecture
+  overview, usage guide, release checklist, and sample files.
+
+### Changed
+
+- Improved help text and error messages to align with user-visible CLI behavior.
+- Tightened provider-neutral import isolation: provider SDKs are not imported
+  unless the relevant extra is installed and the provider is selected.
+
+### Security
+
+- Provider SDKs are optional extras; a user selecting a provider without its
+  SDK receives a clear error rather than an import-time failure at startup.
+- Subtitle source files are never modified by translation or review operations.
+- Consistency reports do not overwrite existing files.
+
+[Unreleased]: https://github.com/dhofverberg/subtitle-translator/compare/v0.9.0...HEAD
+[0.9.0]: https://github.com/dhofverberg/subtitle-translator/releases/tag/v0.9.0

subtranslate_ai-0.9.0/CONTRIBUTING.md

@@ -0,0 +1,169 @@
+# Contributing to Subtitle Translator
+
+Thank you for your interest in contributing! This document covers development
+setup, conventions, and the process for reporting bugs and proposing changes.
+
+## Supported Python versions
+
+Python **3.11, 3.12, and 3.13** are supported and tested in CI.
+
+## Setting up the development environment
+
+1. Clone the repository:
+
+   ```bash
+   git clone https://github.com/dhofverberg/subtitle-translator.git
+   cd subtitle-translator
+   ```
+
+2. Create and activate a virtual environment:
+
+   ```bash
+   python -m venv .venv
+   # macOS / Linux
+   source .venv/bin/activate
+   # Windows PowerShell
+   .venv\Scripts\Activate.ps1
+   ```
+
+3. Install all provider extras and development tools:
+
+   ```bash
+   python -m pip install -e ".[all,dev]"
+   ```
+
+   If you only need one provider:
+
+   ```bash
+   python -m pip install -e ".[openai,dev]"
+   python -m pip install -e ".[gemini,dev]"
+   ```
+
+## Running the tests
+
+```bash
+pytest
+```
+
+Run a specific file:
+
+```bash
+pytest tests/test_cli.py
+```
+
+All automated tests must pass without making real API calls. Use fake/stub
+clients (see `tests/` for examples) whenever provider interactions are tested.
+
+## Running the linter
+
+```bash
+ruff check .
+```
+
+Ruff is configured in `pyproject.toml`. Fix reported issues before opening a
+pull request.
+
+## Building the wheel and source distribution
+
+```bash
+python -m build
+```
+
+Inspect the distribution contents:
+
+```bash
+python -m twine check dist/*
+```
+
+## Verifying the installed wheel
+
+Build the wheel, then install it into a clean environment outside the source
+tree and run the CLI:
+
+```bash
+# macOS / Linux
+python -m venv /tmp/st-verify
+wheel_path="$(python -c 'from pathlib import Path; print(next(Path(\"dist\").glob(\"subtranslate_ai-*.whl\")).resolve())')"
+wheel_uri="$(python -c 'from pathlib import Path; import sys; print(Path(sys.argv[1]).as_uri())' "$wheel_path")"
+/tmp/st-verify/bin/pip install "subtranslate-ai[all] @ $wheel_uri"
+/tmp/st-verify/bin/subtitle-translator --version
+/tmp/st-verify/bin/subtitle-translator --help
+/tmp/st-verify/bin/subtitle-translator translate --help
+/tmp/st-verify/bin/subtitle-translator review --help
+```
+
+```powershell
+# Windows PowerShell
+python -m venv "$env:TEMP\st-verify"
+$wheelPath = (Get-ChildItem dist\subtranslate_ai-*.whl | Select-Object -First 1).FullName
+$wheelUri = python -c "from pathlib import Path; import sys; print(Path(sys.argv[1]).resolve().as_uri())" "$wheelPath"
+& "$env:TEMP\st-verify\Scripts\pip.exe" install "subtranslate-ai[all] @ $wheelUri"
+& "$env:TEMP\st-verify\Scripts\subtitle-translator.exe" --version
+& "$env:TEMP\st-verify\Scripts\subtitle-translator.exe" --help
+& "$env:TEMP\st-verify\Scripts\subtitle-translator.exe" translate --help
+& "$env:TEMP\st-verify\Scripts\subtitle-translator.exe" review --help
+```
+## Architecture overview
+
+See [`docs/architecture.md`](docs/architecture.md) for a concise description of
+the provider-neutral core, translation and review adapters, file boundaries, and
+safety invariants.
+
+## Adding a provider integration
+
+1. Create a new module under `src/subtitle_translator/providers/`.
+2. Implement the `TranslationProvider` interface from `providers/base.py` for
+   translation, or `ConsistencyReviewer` from `consistency.py` for review.
+3. Register the provider in `providers/factory.py`.
+4. Add the provider SDK as an optional extra in `pyproject.toml`.
+5. Write tests using a fake/stub client — do not make real API calls in
+   automated tests.
+6. Do not import the provider SDK at module load time; gate imports behind the
+   point where the provider is first used.
+
+## Keeping the core provider-neutral
+
+The `models.py`, `batch.py`, `srt.py`, `glossary.py`, `consistency.py`, and
+`prompts.py` modules must not import any provider SDK. Verify this with the
+existing provider-neutral import tests.
+
+## Writing tests with fake clients
+
+Provider tests use fake/stub implementations of `TranslationProvider` and
+`ConsistencyReviewer`. See `tests/test_cli_integration.py` for examples. Never
+use `monkeypatch` to replace transport-level calls when a higher-level interface
+can be faked instead.
+
+## Adding changelog entries
+
+Add a one-line summary under the appropriate heading in the `[Unreleased]`
+section of `CHANGELOG.md` for every user-visible change. See the format in that
+file. Do not edit released sections.
+
+## Writing pull requests
+
+- Keep the scope focused: one logical change per PR.
+- Include or update tests for every behavioral change.
+- Ensure `ruff check .` passes.
+- Ensure `pytest` passes.
+- Ensure `python -m build` and `python -m twine check dist/*` pass.
+- Do not commit API keys, provider credentials, or personal environment details.
+- Do not commit copyrighted subtitle files. Use original synthetic content in
+  samples and test fixtures.
+- Update documentation when behavior visible to users changes.
+- Add a changelog entry for every user-visible change.
+
+## Documentation-only changes
+
+Documentation-only changes (README, docs/, CHANGELOG, etc.) do not require
+new tests, but must not break existing ones. Ruff should still pass.
+
+## Reporting bugs and proposing features
+
+Use the GitHub issue tracker:
+<https://github.com/dhofverberg/subtitle-translator/issues>
+
+See the issue templates for the information to include. Never include real API
+keys or private subtitle content in issues.
+
+For security vulnerabilities, see [SECURITY.md](SECURITY.md).

subtranslate_ai-0.9.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Daniel Hofverberg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

subtranslate_ai-0.9.0/MANIFEST.in

@@ -0,0 +1,7 @@
+include README.md
+include CHANGELOG.md
+include CONTRIBUTING.md
+include SECURITY.md
+include LICENSE
+
+recursive-include src/subtitle_translator/resources *.txt