# How to Contribute #

While we are working on NZBGet project all the time, we still would really like and need help on many areas:

- Major - code contributions on features and bugs
- Improvements in tests 
- Improvements on documentation

We entice our users to participate in the project, please don't hesitate to get involved - create a [new issue](https://github.com/nzbgetcom/nzbget/issues/new) or [pull request](https://github.com/nzbgetcom/nzbget/compare) - that would also greatly help if you'll share your usage experience.

## Documentation ##

Main documentation is available on the NZBGet.com website - [https://nzbget.com/documentation/](https://nzbget.com/documentation/)

## Development ##

NZBGet natively supports for multiple platforms and build options, so each platform has their own development documenation, including:

- [General documentation, including Posix](https://github.com/nzbgetcom/nzbget/blob/develop/INSTALLATION.md)
- [Windows](https://github.com/nzbgetcom/nzbget/blob/develop/windows/README-WINDOWS.txt)
- [Docker](https://github.com/nzbgetcom/nzbget/blob/develop/docker/README.md)

### Branches naming policy ###

- `main` is a protected branch that contains only release code
- `develop` is a protected branch for development
- new branches should follow the following convention:
  - `hotfix/brief-description` for any small hotfixes
  - `feature/brief-description` for any new developments
  - `bugfix/brief-description` for bugs

### Pull requests flow for `develop` and `main` branches ### 

1. For PRs targeting `develop` branch `Squash and merge` mode must be used.
2. After merging branch to `develop`, branch must be deleted.
3. For release PR (`develop` -> `main`) `Create a merge commit` mode must be used.
4. After merging `develop` -> `main`, must be back merge `main` -> `develop` before any changes in `develop` branch.

This flow results to the fact that in the PR to master branch we see only the squashed commits that correspond to the PRs in the develop branch in current release cycle.

### Version changes in release cycle

After the release has been published (from the `main` branch), the minor version in the `develop` branch should be increased so that subsequent test builds are a higher version than the release.

List of files to change version:

1. CMakeLists.txt - `project` block
2. osx/NZBGet-Info.plist - `CFBundleShortVersionString` block

### WebUI Internationalization (i18n)

The WebUI uses a client-side i18n system with JSON translation files.

#### File structure

```
webui/
  locales.source.json              — Source of truth: all translation keys with English text and translator descriptions
  i18n.js                          — Runtime engine: loads translations, applies them via data-i18n attributes
  _locales/
    de/messages.json               — Per-language translation files
    fr/messages.json
    ...

  > **Note:** Files under `_locales/` are auto-generated by the translation
  > management process. Do **not** edit them manually — any changes will be
  > overwritten. All translation work should be done in `locales.source.json`
  > (new keys) or through the translation platform (existing keys).
```

#### Adding a new translatable message

1. Add a `data-i18n` attribute to the HTML element:

   ```html
   <span data-i18n="my_new_key"></span>
   ```

   For titles, placeholders, values, or HTML content:

   ```html
   <input data-i18n-title="my_tooltip_key">
   <input data-i18n-placeholder="my_placeholder_key">
   <div data-i18n-html="my_html_key"></div>
   ```

2. If the message has dynamic parts, use `$1`, `$2` placeholders:

   ```html
   <span data-i18n="my_key" data-i18n-arg-1="42"></span>
   ```

3. Add the key to `webui/locales.source.json`:

   ```json
   "my_new_key": {
     "message": "Default English text with $1 placeholder",
     "description": "Brief description for translators"
   }
   ```

4. If the key describes a configuration option (e.g., `MainDir`),
   run `generate_conf_locales.py` to regenerate `config_desc_*` entries:

   ```
   python3 scripts/generate_conf_locales.py nzbget.conf webui/locales.source.json
   ```

5. Translations for non-English languages are managed through an external
   platform/process and stored in `webui/_locales/<code>/messages.json`.
   These files are auto-generated — never edit them directly.
   Missing keys fall back to English automatically.

#### Key naming conventions

| Prefix | Used for |
|--------|----------|
| `col_` | Table column headers |
| `btn_` | Button labels |
| `status_` | Status labels |
| `label_` | General labels and badges |
| `desc_` | Descriptions and tooltips |
| `config_desc_` | Auto-generated config option descriptions |

Use `snake_case` and keep keys short but descriptive.

#### How translation loading works

1. `i18n.js` loads `locales.source.json` — English becomes the base translation.
2. Detects the browser language or reads a saved preference from `localStorage`.
3. If non-English, fetches `_locales/<code>/messages.json` and merges it on top of English.
4. Calls `I18n.translatePage()` which scans the DOM for `data-i18n` attributes and replaces content accordingly.