Metadata-Version: 2.5
Name: mkdocs-autotranslate
Version: 0.2.0
Summary: MkDocs plugin + CLI: detect and fill blog translation gaps between language trees via DeepL.
Project-URL: Homepage, https://github.com/Aldo-f/mkdocs-autotranslate
Project-URL: Repository, https://github.com/Aldo-f/mkdocs-autotranslate
Project-URL: Issues, https://github.com/Aldo-f/mkdocs-autotranslate/issues
Author: Aldo Fieuw
License: MIT License
        
        Copyright (c) 2026 Aldo Fieuw
        
        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.
License-File: LICENSE
Keywords: blog,deepl,i18n,mkdocs,mkdocs-plugin,translation
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Framework :: MkDocs
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Documentation
Classifier: Topic :: Software Development :: Documentation
Classifier: Topic :: Text Processing :: Markup :: Markdown
Requires-Python: >=3.10
Requires-Dist: mkdocs>=1.5
Provides-Extra: test
Requires-Dist: pytest>=8; extra == 'test'
Description-Content-Type: text/markdown

# mkdocs-autotranslate

A MkDocs plugin + CLI that keeps a multilingual MkDocs site in sync across
language trees: it detects content that exists in one language but not
another — blog posts, pages, any path you point it at — and can create the
missing translations via [DeepL](https://www.deepl.com/).

- **Plugin** (`autotranslate`): at build time, reports untranslated
  content — optionally fails strict builds. Never touches the network.
- **CLI** (`autotranslate`): dry-run report by default; `--write`
  creates missing translated files for human review before commit.

## Install

```bash
pip install mkdocs-autotranslate
```

## Plugin usage

Add to `mkdocs.yml`:

```yaml
plugins:
  - autotranslate:
      languages: [en, nl]     # directories under docs/
      paths: [blog/posts]     # dirs/files/globs under each language dir
      mode: report            # report | strict (fail build on gaps)
```

With Material's multi-language recipe you typically run one build per
language config; add the plugin to each (or the shared base config).

## CLI usage

```bash
# dry-run: shows what WOULD be created, writes nothing, needs no API key
autotranslate --docs-dir docs

# apply: creates missing posts via DeepL (review the git diff!)
autotranslate --docs-dir docs --write
```

Options:

| Flag | Default | Meaning |
|---|---|---|
| `--docs-dir` | (required) | Path to your `docs/` directory |
| `--languages` | `en nl` | Language subdirectories to compare |
| `--paths` | `blog/posts` | Dirs/files/globs under each language dir |
| `--write` | off | Create files instead of reporting only |

## DeepL key

The CLI looks for a DeepL auth key in `$DEEPL_API_KEY` or
`~/.config/deepl/api_key` (mode 0600). Keys ending in `:fx` automatically
use the free endpoint (`api-free.deepl.com`); all others use the pro
endpoint. Free tier is 500,000 characters/month.

## Guarantees

- Never overwrites existing files (idempotent; re-runs are no-ops)
- Drafts (`draft: true`) are never propagated
- Front matter preserved structurally: title translated, date/categories verbatim
- Fenced code blocks pass through untranslated
- A provenance comment is appended to generated files
- The plugin itself performs no network calls — translation is always an
  explicit author-run step so machine output gets reviewed before publishing

## Development

```bash
pip install -e '.[test]'
pytest
```

## License

MIT
