Metadata-Version: 2.4
Name: nvda-addon-kit
Version: 0.1.0
Summary: Scaffold, build, translate and install NVDA add-ons from a single addon.toml
Keywords: nvda,addon,accessibility,screen-reader,build,gettext
Author: Beka Gozalishvili
Author-email: Beka Gozalishvili <beqaprogger@gmail.com>
License-Expression: GPL-2.0-or-later
License-File: COPYING.txt
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Adaptive Technologies
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Localization
Requires-Dist: babel==2.18.0
Requires-Dist: tomlkit==0.15.1
Requires-Dist: markdown==3.10.3
Requires-Dist: crowdin-api-client==1.28.0 ; extra == 'crowdin'
Requires-Python: >=3.13
Project-URL: Repository, https://github.com/addonfactory/NVDAAddonKit
Project-URL: Issues, https://github.com/addonfactory/NVDAAddonKit/issues
Provides-Extra: crowdin
Description-Content-Type: text/markdown

# nvda-addon-kit

Scaffold, build, translate and install [NVDA](https://www.nvaccess.org/) add-ons from a single
`addon.toml`.

This is the successor to the SCons-based `addonTemplate`. Instead of forking a template repository and editing `buildVars.py`, you install a tool:

```console
pip install nvda-addon-kit
nvaddon init myAddon
cd myAddon
nvaddon build
```

## Commands

| Command | Does |
| --- | --- |
| `nvaddon init [dir]` | Create a new add-on, interactively or from flags |
| `nvaddon build` | Produce `<name>-<version>.nvda-addon` |
| `nvaddon install` | Build, then hand the add-on to NVDA to install |
| `nvaddon install --link` | Link the working tree into NVDA's add-ons directory for development |
| `nvaddon pot` | Generate `<name>.pot` from Python sources and `addon.toml` |
| `nvaddon locale-add <lang>…` | Start a new translation |
| `nvaddon locale-update` | Merge new messages into every existing translation |
| `nvaddon locale-compile` | Compile `.po` files and translated manifests |
| `nvaddon check` | Validate `addon.toml` against add-on store rules |
| `nvaddon clean` | Remove generated build outputs |
| `nvaddon migrate` | Convert an existing `buildVars.py` to `addon.toml` |
| `nvaddon release <version>` | Set version and channel, commit, tag `<version>-<channel>`, and push |
| `nvaddon crowdin` | Sync translations with Crowdin |

Run `nvaddon <command> --help` for the flags each one accepts.

## Releasing

```console
nvaddon release 1.2.0 --channel beta
```

This writes the version and channel into `addon.toml`, commits, tags
`1.2.0-beta`, and pushes the commit and tag with `git push --atomic` so the
remote takes both or neither. If anything fails the working tree is restored to
where it started, leaving no half-made release behind. Use `--no-push` to stop
before publishing.

## addon.toml

```toml
[addon]
name = "myAddon"
# Translators: Summary/title for this add-on, shown on install and in the add-on store.
summary = "Add-on user visible name"
# Translators: Long description shown for this add-on in the add-on store.
description = """Description for the add-on.
It can span multiple lines."""
version = "1.0.0"
author = "Name <name@domain.com>"
minimumNVDAVersion = "2024.1"
lastTestedNVDAVersion = "2025.3"

[build]
pythonSources = ["addon/globalPlugins/**/*.py"]

[l10n]
baseLanguage = "en"
```

The comment above a translatable key becomes that string's translator note in the generated
`.pot`, exactly as `# Translators:` comments in `buildVars.py` did:

```pot
#. Translators: Summary/title for this add-on, shown on install and in the add-on store.
#: addon.toml:3
msgid "Add-on user visible name"
msgstr ""
```

## Migrating an existing add-on

```console
cd myExistingAddon
pip install nvda-addon-kit
nvaddon migrate
nvaddon check
nvaddon build
```

`migrate` leaves `buildVars.py`, `sconstruct` and `site_scons/` in place; delete them once you
are satisfied the build output matches.

## Licence

GNU General Public License version 2 or later. See [COPYING.txt](COPYING.txt).
